Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Gate the stable npm publish on a DMG smoke, and page when it refuses (#2959)

Andrew Mikofalvy32f8756e3edf
diff --git a/.github/scripts/build-smoke-alert-payload.mjs b/.github/scripts/build-smoke-alert-payload.mjs
new file mode 100644
index 000000000..2f183af46
--- /dev/null
+++ b/.github/scripts/build-smoke-alert-payload.mjs
@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * Alert payloads for a blocked release (FR5c).
+ *
+ * When the DMG smoke gate refuses a release, the operator needs to learn it
+ * from the channel they already watch, not by noticing that a release never
+ * appeared. This builds the Slack and Discord payloads for that page.
+ *
+ * The alert must be UNMISTAKABLY different from the routine
+ * "πŸŽ‰ OpenKnowledge X.Y.Z released" announcement that posts to the same
+ * channels: different emoji, different headline, red rather than blue, and an
+ * explicit statement that nothing shipped. A reader scanning the channel has
+ * to be able to tell a blocked release from a successful one at a glance.
+ *
+ * Usage:
+ * node build-smoke-alert-payload.mjs --channel slack|discord \
+ * --tag vX.Y.Z --verdict fail|error --reason "…" --run-url "…" [--repo owner/name]
+ *
+ * Emits the payload as JSON on stdout. Everything is assembled through
+ * JSON.stringify, so an interpolated tag or reason containing quotes cannot
+ * corrupt the body.
+ */
+
+import { pathToFileURL } from 'node:url';
+
+/** Red. The routine release announcement uses 3638527 (blue) β€” see desktop-release.yml. */
+export const ALERT_COLOR_DECIMAL = 14357800; // #DB1E28
+const ALERT_HEADLINE = 'RELEASE BLOCKED';
+const DEFAULT_REPO = 'inkeep/open-knowledge';
+
+/**
+ * A `fail` means the app itself misbehaved; an `error` means the gate could not
+ * reach a verdict. The responder does different things in each case, so the
+ * two must never read the same.
+ */
+export function describeVerdict(verdict) {
+ if (verdict === 'fail') {
+ return {
+ short: 'FAILED',
+ detail: 'the packaged app failed the smoke subset β€” treat this as a real product regression',
+ };
+ }
+ return {
+ short: 'ERRORED',
+ detail:
+ 'the gate hit an infrastructure error and never reached a verdict β€” the app may be fine; re-run before assuming a regression',
+ };
+}
+
+/** Re-firing the two dispatch events is the whole recovery; nothing needs repair by hand. */
+export function recoveryCommand(tag, repo = DEFAULT_REPO) {
+ return [
+ `gh api -X POST repos/${repo}/dispatches -f event_type=desktop-release`,
+ `-F 'client_payload[release_tag]=${tag}' -F 'client_payload[ref]=${tag}'`,
+ ].join(' ');
+}
+
+function summaryLine(tag, verdict) {
+ const { short } = describeVerdict(verdict);
+ return `🚨 ${ALERT_HEADLINE}: ${tag} DMG smoke ${short} β€” nothing shipped`;
+}
+
+function bodyLines({ tag, verdict, reason, runUrl, repo }) {
+ const { detail } = describeVerdict(verdict);
+ return [
+ `*Tag:* \`${tag}\``,
+ `*Verdict:* \`${verdict}\` β€” ${detail}`,
+ `*Why:* ${reason}`,
+ '*State:* the GitHub Release is still a DRAFT and npm `latest` has NOT moved.',
+ `*Recovery (re-fire the cascade; no manual repair needed):*\n\`${recoveryCommand(tag, repo)}\``,
+ `*Run:* ${runUrl}`,
+ ];
+}
+
+export function buildSlackPayload({ tag, verdict, reason, runUrl, repo = DEFAULT_REPO }) {
+ return {
+ // `text` is the notification / a11y fallback Slack recommends alongside blocks.
+ text: summaryLine(tag, verdict),
+ blocks: [
+ {
+ type: 'header',
+ text: { type: 'plain_text', text: summaryLine(tag, verdict), emoji: true },
+ },
+ {
+ type: 'section',
+ text: {
+ type: 'mrkdwn',
+ text: bodyLines({ tag, verdict, reason, runUrl, repo }).join('\n'),
+ },
+ },
+ ],
+ };
+}
+
+export function buildDiscordPayload({ tag, verdict, reason, runUrl, repo = DEFAULT_REPO }) {
+ return {
+ username: 'OpenKnowledge',
+ allowed_mentions: { parse: [] },
+ content: summaryLine(tag, verdict),
+ embeds: [
+ {
+ title: summaryLine(tag, verdict),
+ url: runUrl,
+ color: ALERT_COLOR_DECIMAL,
+ description: bodyLines({ tag, verdict, reason, runUrl, repo })
+ .join('\n')
+ // Slack mrkdwn bolds with single asterisks; Discord needs two.
+ .replace(/\*([^*]+)\*/g, '**$1**'),
+ },
+ ],
+ };
+}
+
+export function parseArgs(argv) {
+ const args = {};
+ const rest = argv.slice(2);
+ for (let i = 0; i < rest.length; i += 1) {
+ const key = rest[i];
+ if (!key.startsWith('--')) continue;
+ args[key.slice(2)] = rest[i + 1] ?? '';
+ i += 1;
+ }
+ if (!args.channel || !['slack', 'discord'].includes(args.channel)) {
+ throw new Error('--channel must be "slack" or "discord"');
+ }
+ if (!args.tag) throw new Error('--tag is required');
+ return {
+ channel: args.channel,
+ tag: args.tag,
+ verdict: args.verdict || 'error',
+ reason: args.reason || '(no reason recorded)',
+ runUrl: args['run-url'] || '',
+ repo: args.repo || DEFAULT_REPO,
+ };
+}
+
+export function buildPayload(opts) {
+ return opts.channel === 'slack' ? buildSlackPayload(opts) : buildDiscordPayload(opts);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+ try {
+ process.stdout.write(JSON.stringify(buildPayload(parseArgs(process.argv))));
+ } catch (err) {
+ process.stderr.write(`${err.message}\n`);
+ process.exit(1);
+ }
+}
diff --git a/.github/scripts/build-smoke-alert-payload.test.mjs b/.github/scripts/build-smoke-alert-payload.test.mjs
new file mode 100644
index 000000000..ea8407615
--- /dev/null
+++ b/.github/scripts/build-smoke-alert-payload.test.mjs
@@ -0,0 +1,208 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, test } from 'vitest';
+import {
+ ALERT_COLOR_DECIMAL,
+ buildDiscordPayload,
+ buildPayload,
+ buildSlackPayload,
+ describeVerdict,
+ parseArgs,
+ recoveryCommand,
+} from './build-smoke-alert-payload.mjs';
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const desktopRelease = readFileSync(
+ join(REPO_ROOT, '.github', 'workflows', 'desktop-release.yml'),
+ 'utf8',
+);
+
+const base = {
+ tag: 'v1.2.3',
+ verdict: 'fail',
+ reason: '2 of 16 executed smoke tests failed against the packaged app',
+ runUrl: 'https://github.com/inkeep/open-knowledge/actions/runs/999',
+};
+
+describe('alert content', () => {
+ test('names the tag, verdict, run link, and recovery command', () => {
+ const slack = JSON.stringify(buildSlackPayload(base));
+ for (const needle of ['v1.2.3', 'fail', base.runUrl, 'event_type=desktop-release']) {
+ expect(slack).toContain(needle);
+ }
+ const discord = JSON.stringify(buildDiscordPayload(base));
+ for (const needle of ['v1.2.3', 'fail', base.runUrl, 'event_type=desktop-release']) {
+ expect(discord).toContain(needle);
+ }
+ });
+
+ test('states that nothing shipped', () => {
+ const slack = JSON.stringify(buildSlackPayload(base));
+ expect(slack).toContain('nothing shipped');
+ expect(slack).toContain('DRAFT');
+ expect(slack).toContain('npm `latest` has NOT moved');
+ });
+
+ test('a genuine failure and an infrastructure error read differently', () => {
+ // The responder does different things in each case: a fail is a product
+ // regression to investigate; an error may just need a re-run.
+ const fail = JSON.stringify(buildSlackPayload({ ...base, verdict: 'fail' }));
+ const error = JSON.stringify(buildSlackPayload({ ...base, verdict: 'error' }));
+ expect(fail).not.toBe(error);
+ expect(fail).toContain('FAILED');
+ expect(error).toContain('ERRORED');
+ expect(fail).toContain('real product regression');
+ expect(error).toContain('never reached a verdict');
+ expect(describeVerdict('fail').short).not.toBe(describeVerdict('error').short);
+ });
+
+ test('the recovery command re-fires the cascade for the right tag', () => {
+ expect(recoveryCommand('v9.9.9')).toContain('client_payload[release_tag]=v9.9.9');
+ expect(recoveryCommand('v9.9.9', 'acme/fork')).toContain('repos/acme/fork/dispatches');
+ });
+});
+
+describe('distinctness from the routine release announcement', () => {
+ test('does not reuse the celebratory headline or the announcement colour', () => {
+ const slack = JSON.stringify(buildSlackPayload(base));
+ const discord = buildDiscordPayload(base);
+ expect(slack).not.toContain('πŸŽ‰');
+ expect(slack).not.toContain('released');
+ expect(slack).toContain('🚨');
+ expect(slack).toContain('RELEASE BLOCKED');
+ // 3638527 is the blue the routine announcement uses in desktop-release.yml.
+ expect(desktopRelease).toContain('color: 3638527');
+ expect(discord.embeds[0].color).toBe(ALERT_COLOR_DECIMAL);
+ expect(discord.embeds[0].color).not.toBe(3638527);
+ });
+
+ test('the Discord alert suppresses mentions like the announcement does', () => {
+ expect(buildDiscordPayload(base).allowed_mentions).toEqual({ parse: [] });
+ });
+
+ test('bold markup is Discord-flavoured in the Discord payload', () => {
+ const discord = buildDiscordPayload(base);
+ expect(discord.embeds[0].description).toContain('**Tag:**');
+ expect(discord.embeds[0].description).not.toMatch(/(^|[^*])\*Tag:\*/);
+ // Slack keeps its own single-asterisk mrkdwn.
+ expect(buildSlackPayload(base).blocks[1].text.text).toContain('*Tag:*');
+ });
+});
+
+describe('escaping', () => {
+ test('quotes and newlines in interpolated values cannot corrupt the JSON', () => {
+ const nasty = {
+ ...base,
+ tag: 'v1.0.0"; rm -rf /; echo "',
+ reason: 'line one\nline "two" \\ backslash',
+ };
+ const slack = buildSlackPayload(nasty);
+ const roundTripped = JSON.parse(JSON.stringify(slack));
+ expect(roundTripped.text).toContain('v1.0.0"; rm -rf /; echo "');
+ expect(JSON.stringify(buildDiscordPayload(nasty))).toContain('line one\\nline');
+ });
+});
+
+describe('parseArgs', () => {
+ const argv = (...rest) => ['node', 'x', ...rest];
+
+ test('reads every flag the workflow step passes', () => {
+ const parsed = parseArgs(
+ argv(
+ '--channel',
+ 'discord',
+ '--tag',
+ 'v1.2.3',
+ '--verdict',
+ 'error',
+ '--reason',
+ 'mount failed',
+ '--run-url',
+ 'https://example.test/run',
+ ),
+ );
+ expect(parsed).toEqual({
+ channel: 'discord',
+ tag: 'v1.2.3',
+ verdict: 'error',
+ reason: 'mount failed',
+ runUrl: 'https://example.test/run',
+ repo: 'inkeep/open-knowledge',
+ });
+ });
+
+ test('rejects a missing or unknown channel rather than emitting a half-built payload', () => {
+ expect(() => parseArgs(argv('--tag', 'v1'))).toThrow(/--channel/);
+ expect(() => parseArgs(argv('--channel', 'email', '--tag', 'v1'))).toThrow(/--channel/);
+ });
+
+ test('rejects a missing tag', () => {
+ expect(() => parseArgs(argv('--channel', 'slack'))).toThrow(/--tag/);
+ });
+
+ test('defaults an absent verdict to error rather than silently claiming a pass', () => {
+ expect(parseArgs(argv('--channel', 'slack', '--tag', 'v1')).verdict).toBe('error');
+ });
+
+ test('buildPayload dispatches on channel', () => {
+ expect(buildPayload({ ...base, channel: 'slack' }).blocks).toBeDefined();
+ expect(buildPayload({ ...base, channel: 'discord' }).embeds).toBeDefined();
+ });
+});
+
+describe('workflow wiring', () => {
+ test('the alert step is failure-conditioned, not success-conditioned', () => {
+ const step = desktopRelease.slice(desktopRelease.indexOf('- name: Alert on a blocked release'));
+ expect(step.slice(0, 400)).toContain('if: failure()');
+ expect(step.slice(0, 400)).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 = desktopRelease.slice(desktopRelease.indexOf('- name: Alert on a blocked release'));
+ expect(step).toContain('git fetch --depth=1 origin "$GITHUB_SHA"');
+ expect(step).toContain(
+ 'git show "${GITHUB_SHA}:.github/scripts/build-smoke-alert-payload.mjs"',
+ );
+ });
+
+ test('the alert reuses the existing webhook secrets and introduces none', () => {
+ const step = desktopRelease
+ .slice(desktopRelease.indexOf('- name: Alert on a blocked release'))
+ .slice(0, 4000);
+ expect(step).toContain('secrets.SLACK_WEBHOOK_URL');
+ expect(step).toContain('secrets.DISCORD_WEBHOOK_URL');
+ const secretNames = new Set(
+ [...desktopRelease.matchAll(/secrets\.([A-Z0-9_]+)/g)].map((m) => m[1]),
+ );
+ expect(secretNames.has('SLACK_WEBHOOK_URL')).toBe(true);
+ expect(secretNames.has('DISCORD_WEBHOOK_URL')).toBe(true);
+ });
+
+ test('an unset webhook is a notice-level skip, and a failed POST is a warning', () => {
+ const step = desktopRelease
+ .slice(desktopRelease.indexOf('- name: Alert on a blocked release'))
+ .slice(0, 5000);
+ // Unset secret: annotate and return 0 β€” never fail the step.
+ expect(step).toContain('::notice::${label} webhook not set');
+ expect(step).toMatch(/if \[\[ -z "\$webhook" \]\]; then[\s\S]{0,200}?return 0/);
+ // A dead webhook warns; it must not mask the smoke failure that caused it.
+ expect(step).toContain('::warning::${label} smoke alert failed to POST');
+ // Both channels are actually driven.
+ expect(step).toContain('post slack "${SLACK_WEBHOOK_URL:-}"');
+ expect(step).toContain('post discord "${DISCORD_WEBHOOK_URL:-}"');
+ });
+
+ test('the annotation is emitted in addition to the page, not instead of it', () => {
+ const step = desktopRelease
+ .slice(desktopRelease.indexOf('- name: Alert on a blocked release'))
+ .slice(0, 5000);
+ const slackAt = step.indexOf('post slack');
+ const annotationAt = step.indexOf('::error::RELEASE BLOCKED');
+ expect(slackAt).toBeGreaterThan(-1);
+ expect(annotationAt).toBeGreaterThan(slackAt);
+ });
+});
diff --git a/.github/scripts/dmg-mount.mjs b/.github/scripts/dmg-mount.mjs
new file mode 100644
index 000000000..80ced0a0b
--- /dev/null
+++ b/.github/scripts/dmg-mount.mjs
@@ -0,0 +1,171 @@
+/**
+ * Shared hdiutil mount/copy/detach primitive for packaged-DMG drivers.
+ *
+ * `withMountedDmg` attaches a `.dmg` read-only, copies the first `.app` bundle
+ * out to a temporary directory, detaches the mount, and only then hands the
+ * COPIED bundle to the caller. Launching from the copy rather than the live
+ * mount is the whole point: a packaged smoke run holds the app open for
+ * minutes, and a mount held for that window is what strands `/Volumes` entries
+ * when CI kills the run.
+ *
+ * SIGINT/SIGTERM are handled explicitly because Node's default on both is a
+ * synchronous exit that skips `finally` β€” which would leave the volume attached
+ * until someone runs `hdiutil detach` by hand or reboots the runner. Handlers
+ * are registered per invocation and removed in `finally` so a long-lived
+ * process that mounts repeatedly does not accumulate listeners.
+ *
+ * Every external effect is injectable via `deps` so the colocated test covers
+ * each branch without invoking real hdiutil.
+ */
+
+import { spawn } from 'node:child_process';
+import { cp, mkdtemp, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+/**
+ * Discriminants for the two ways a mount can fail structurally. Callers map
+ * these to an infrastructure verdict rather than a product verdict β€” a DMG that
+ * cannot be mounted says nothing about whether the app works.
+ */
+export const MOUNT_ERROR_CODES = {
+ attachFailed: 'dmg-attach-failed',
+ noAppBundle: 'dmg-no-app-bundle',
+};
+
+export class DmgMountError extends Error {
+ constructor(message, code) {
+ super(message);
+ this.name = 'DmgMountError';
+ this.code = code;
+ }
+}
+
+async function defaultRunCommand(cmd, args) {
+ return await new Promise((resolvePromise, rejectPromise) => {
+ const child = spawn(cmd, args, { stdio: 'pipe' });
+ const stderrBuf = [];
+ child.stderr?.on('data', (d) => stderrBuf.push(d.toString('utf-8')));
+ child.on('exit', (code) => {
+ if (code === 0) resolvePromise();
+ else rejectPromise(new Error(`${cmd} exited ${code}: ${stderrBuf.join('').trim()}`));
+ });
+ child.on('error', (err) => rejectPromise(err));
+ });
+}
+
+async function defaultListAppsInMount(mountPath) {
+ const entries = await readdir(mountPath);
+ return entries.filter((e) => e.toLowerCase().endsWith('.app'));
+}
+
+/**
+ * Mount `dmgPath`, copy its first `.app` out, detach, then invoke `callback`
+ * with the path to the copied bundle. The copy and the mountpoint are removed
+ * before returning, whether the callback resolved or threw.
+ *
+ * Returns whatever `callback` returns.
+ */
+export async function withMountedDmg(dmgPath, callback, deps = {}) {
+ const runCommand = deps.runCommand ?? defaultRunCommand;
+ const mkdtempImpl = deps.mkdtemp ?? mkdtemp;
+ const cpImpl = deps.cp ?? cp;
+ const rmImpl = deps.rm ?? rm;
+ const listAppsInMount = deps.listAppsInMount ?? defaultListAppsInMount;
+ const proc = deps.process ?? process;
+
+ const abs = resolve(dmgPath);
+ const mountRoot = await mkdtempImpl(join(tmpdir(), 'ok-dmg-mount-'));
+ const appCopyRoot = await mkdtempImpl(join(tmpdir(), 'ok-dmg-app-'));
+
+ // `defaultRunCommand` spawns with stdio: 'pipe', so hdiutil's stderr lands in
+ // the Error message rather than the terminal. Swallowing these errors without
+ // logging leaves a stranded /Volumes entry β€” or an orphaned ~200MB .app copy β€”
+ // with no breadcrumb, which on a long-lived runner surfaces much later as an
+ // "already mounted" or disk-full failure with no trail back to here.
+ const warn = deps.warn ?? ((msg) => process.stderr.write(`[dmg-mount] ${msg}\n`));
+ const describe = (err) => err?.message ?? String(err);
+
+ let detached = false;
+ const detach = async () => {
+ if (detached) return;
+ detached = true;
+ try {
+ await runCommand('hdiutil', ['detach', '-quiet', mountRoot]);
+ } catch (err) {
+ // Log, don't throw: throwing here would mask whichever error sent us
+ // into cleanup.
+ warn(`hdiutil detach failed for ${mountRoot}: ${describe(err)}`);
+ }
+ };
+
+ const removeScratch = async () => {
+ // `force: true` already absorbs ENOENT; what reaches these handlers is
+ // EPERM / EBUSY / read-only-filesystem, all worth a line.
+ await rmImpl(appCopyRoot, { recursive: true, force: true }).catch((err) => {
+ warn(`could not remove ${appCopyRoot}: ${describe(err)}`);
+ });
+ await rmImpl(mountRoot, { recursive: true, force: true }).catch((err) => {
+ warn(`could not remove ${mountRoot}: ${describe(err)}`);
+ });
+ };
+
+ let signalHandled = false;
+ async function signalCleanupAndExit(exitCode) {
+ if (signalHandled) return;
+ signalHandled = true;
+ try {
+ await detach();
+ await removeScratch();
+ } finally {
+ proc.exit(exitCode);
+ }
+ }
+ const sigintHandler = () => {
+ void signalCleanupAndExit(130);
+ };
+ const sigtermHandler = () => {
+ void signalCleanupAndExit(143);
+ };
+ proc.once('SIGINT', sigintHandler);
+ proc.once('SIGTERM', sigtermHandler);
+
+ try {
+ try {
+ await runCommand('hdiutil', [
+ 'attach',
+ '-nobrowse',
+ '-readonly',
+ '-mountpoint',
+ mountRoot,
+ abs,
+ ]);
+ } catch (err) {
+ throw new DmgMountError(
+ `hdiutil attach failed for ${abs}: ${err?.message ?? String(err)}`,
+ MOUNT_ERROR_CODES.attachFailed,
+ );
+ }
+
+ const apps = await listAppsInMount(mountRoot);
+ if (apps.length === 0) {
+ await detach();
+ throw new DmgMountError(
+ `No .app bundle found in mounted DMG: ${abs}`,
+ MOUNT_ERROR_CODES.noAppBundle,
+ );
+ }
+
+ const appName = apps[0];
+ const appCopyPath = join(appCopyRoot, appName);
+ await cpImpl(join(mountRoot, appName), appCopyPath, { recursive: true });
+ await detach();
+
+ return await callback(appCopyPath);
+ } finally {
+ proc.removeListener('SIGINT', sigintHandler);
+ proc.removeListener('SIGTERM', sigtermHandler);
+ await detach();
+ await removeScratch();
+ }
+}
diff --git a/.github/scripts/dmg-mount.test.mjs b/.github/scripts/dmg-mount.test.mjs
new file mode 100644
index 000000000..41a3b3234
--- /dev/null
+++ b/.github/scripts/dmg-mount.test.mjs
@@ -0,0 +1,246 @@
+import { EventEmitter } from 'node:events';
+import { describe, expect, test } from 'vitest';
+import { DmgMountError, MOUNT_ERROR_CODES, withMountedDmg } from './dmg-mount.mjs';
+
+/**
+ * Build an injectable dep bundle with a recording command runner. `attachFails`
+ * makes the `hdiutil attach` invocation reject with a stderr-bearing message;
+ * `apps` controls what the mounted volume appears to contain.
+ */
+function makeDeps({ attachFails = false, apps = ['OpenKnowledge.app'], proc } = {}) {
+ const calls = [];
+ const removed = [];
+ let tmpCounter = 0;
+ return {
+ calls,
+ removed,
+ deps: {
+ runCommand: async (cmd, args) => {
+ calls.push([cmd, ...args]);
+ if (attachFails && args[0] === 'attach') {
+ throw new Error('hdiutil exited 1: no mountable file systems');
+ }
+ },
+ mkdtemp: async (prefix) => `${prefix}${++tmpCounter}`,
+ cp: async () => {},
+ rm: async (p) => {
+ removed.push(p);
+ },
+ listAppsInMount: async () => apps,
+ process: proc ?? new EventEmitter(),
+ },
+ };
+}
+
+/** A stand-in for `process` that records `exit` instead of terminating. */
+function fakeProcess() {
+ const emitter = new EventEmitter();
+ emitter.exitCodes = [];
+ emitter.exit = (code) => {
+ emitter.exitCodes.push(code);
+ };
+ return emitter;
+}
+
+describe('withMountedDmg', () => {
+ test('mounts read-only + nobrowse, copies the app out, detaches, then calls back', async () => {
+ const { calls, deps } = makeDeps();
+ let seen = null;
+
+ const result = await withMountedDmg(
+ '/tmp/OpenKnowledge.dmg',
+ async (appPath) => {
+ seen = appPath;
+ // The mount is already released by the time the callback runs β€” that
+ // is the invariant that keeps a long app launch from holding /Volumes.
+ expect(calls.some((c) => c[0] === 'hdiutil' && c[1] === 'detach')).toBe(true);
+ return 'callback-result';
+ },
+ deps,
+ );
+
+ expect(result).toBe('callback-result');
+ expect(seen).toMatch(/OpenKnowledge\.app$/);
+ // The copy lives under a distinct tmp root, never inside the mountpoint.
+ expect(seen).not.toMatch(/ok-dmg-mount-/);
+
+ const attach = calls.find((c) => c[1] === 'attach');
+ expect(attach).toBeDefined();
+ expect(attach).toContain('-nobrowse');
+ expect(attach).toContain('-readonly');
+ expect(attach).toContain('-mountpoint');
+ });
+
+ test('detaches before the callback error propagates', async () => {
+ const { calls, deps } = makeDeps();
+
+ await expect(
+ withMountedDmg(
+ '/tmp/OpenKnowledge.dmg',
+ async () => {
+ throw new Error('smoke run blew up');
+ },
+ deps,
+ ),
+ ).rejects.toThrow('smoke run blew up');
+
+ expect(calls.filter((c) => c[1] === 'detach')).toHaveLength(1);
+ });
+
+ test('cleans up the copy and the mountpoint even when the callback throws', async () => {
+ const { removed, deps } = makeDeps();
+
+ await expect(
+ withMountedDmg(
+ '/tmp/OpenKnowledge.dmg',
+ async () => {
+ throw new Error('boom');
+ },
+ deps,
+ ),
+ ).rejects.toThrow('boom');
+
+ expect(removed.some((p) => p.includes('ok-dmg-app-'))).toBe(true);
+ expect(removed.some((p) => p.includes('ok-dmg-mount-'))).toBe(true);
+ });
+
+ test('attach failure throws with the hdiutil stderr and leaves no mountpoint behind', async () => {
+ const { removed, deps } = makeDeps({ attachFails: true });
+ let called = false;
+
+ const err = await withMountedDmg(
+ '/tmp/broken.dmg',
+ async () => {
+ called = true;
+ },
+ deps,
+ ).catch((e) => e);
+
+ expect(called).toBe(false);
+ expect(err).toBeInstanceOf(DmgMountError);
+ expect(err.code).toBe(MOUNT_ERROR_CODES.attachFailed);
+ expect(err.message).toContain('no mountable file systems');
+ expect(removed.some((p) => p.includes('ok-dmg-mount-'))).toBe(true);
+ });
+
+ test('an empty volume detaches and throws a distinct no-app-bundle error', async () => {
+ const { calls, deps } = makeDeps({ apps: [] });
+
+ const err = await withMountedDmg('/tmp/empty.dmg', async () => 'unreachable', deps).catch(
+ (e) => e,
+ );
+
+ expect(err).toBeInstanceOf(DmgMountError);
+ expect(err.code).toBe(MOUNT_ERROR_CODES.noAppBundle);
+ expect(err.code).not.toBe(MOUNT_ERROR_CODES.attachFailed);
+ expect(calls.filter((c) => c[1] === 'detach')).toHaveLength(1);
+ });
+
+ test('SIGTERM while the callback runs detaches and exits', async () => {
+ const proc = fakeProcess();
+ const { calls, deps } = makeDeps({ proc });
+
+ await withMountedDmg(
+ '/tmp/OpenKnowledge.dmg',
+ async () => {
+ // Simulate the runner killing us mid-smoke. `withMountedDmg` detaches
+ // eagerly before the callback, so assert the handler is wired and the
+ // process is asked to exit with the signal's conventional code.
+ proc.emit('SIGTERM');
+ await Promise.resolve();
+ },
+ deps,
+ );
+
+ expect(proc.exitCodes).toEqual([143]);
+ expect(calls.some((c) => c[1] === 'detach')).toBe(true);
+ });
+
+ test('SIGINT during mount acquisition detaches before exiting', async () => {
+ const proc = fakeProcess();
+ const calls = [];
+ const removed = [];
+ let tmpCounter = 0;
+
+ await withMountedDmg('/tmp/OpenKnowledge.dmg', async () => {}, {
+ runCommand: async (cmd, args) => {
+ calls.push([cmd, ...args]);
+ if (args[0] === 'attach') {
+ // Signal arrives while the volume is attaching β€” the window where
+ // Node's default synchronous exit would strand the mount.
+ proc.emit('SIGINT');
+ await Promise.resolve();
+ }
+ },
+ mkdtemp: async (prefix) => `${prefix}${++tmpCounter}`,
+ cp: async () => {},
+ rm: async (p) => {
+ removed.push(p);
+ },
+ listAppsInMount: async () => ['OpenKnowledge.app'],
+ process: proc,
+ });
+
+ expect(proc.exitCodes).toEqual([130]);
+ expect(calls.some((c) => c[1] === 'detach')).toBe(true);
+ expect(removed.some((p) => p.includes('ok-dmg-mount-'))).toBe(true);
+ });
+
+ test('de-registers its signal handlers so repeated mounts do not leak listeners', async () => {
+ const proc = fakeProcess();
+
+ for (let i = 0; i < 5; i += 1) {
+ const { deps } = makeDeps({ proc });
+ await withMountedDmg('/tmp/OpenKnowledge.dmg', async () => {}, deps);
+ }
+
+ expect(proc.listenerCount('SIGINT')).toBe(0);
+ expect(proc.listenerCount('SIGTERM')).toBe(0);
+ });
+
+ test('de-registers its signal handlers when the mount fails', async () => {
+ const proc = fakeProcess();
+ const { deps } = makeDeps({ attachFails: true, proc });
+
+ await withMountedDmg('/tmp/broken.dmg', async () => {}, deps).catch(() => {});
+
+ expect(proc.listenerCount('SIGINT')).toBe(0);
+ expect(proc.listenerCount('SIGTERM')).toBe(0);
+ });
+});
+
+describe('cleanup failures are logged, not silently swallowed', () => {
+ // hdiutil is spawned with stdio: 'pipe', so its stderr lands in the Error
+ // message rather than the terminal. Swallowing it leaves a stranded mount or
+ // an orphaned ~200MB .app copy with no breadcrumb β€” the symptom surfaces
+ // much later as "already mounted" or disk-full, with no trail back here.
+ test('a failing detach warns and still does not throw', async () => {
+ const warnings = [];
+ const { deps } = makeDeps();
+ deps.runCommand = async (_cmd, args) => {
+ if (args[0] === 'detach') throw new Error('hdiutil: detach failed - Resource busy');
+ return undefined;
+ };
+ deps.warn = (m) => warnings.push(m);
+
+ await expect(withMountedDmg('/tmp/OpenKnowledge.dmg', async () => 'ok', deps)).resolves.toBe(
+ 'ok',
+ );
+ expect(warnings.join('\n')).toContain('Resource busy');
+ expect(warnings.join('\n')).toContain('detach failed');
+ });
+
+ test('a failing scratch removal warns for each path', async () => {
+ const warnings = [];
+ const { deps } = makeDeps();
+ deps.rm = async (p) => {
+ throw new Error(`EPERM: operation not permitted, rm '${p}'`);
+ };
+ deps.warn = (m) => warnings.push(m);
+
+ await withMountedDmg('/tmp/OpenKnowledge.dmg', async () => {}, deps);
+ expect(warnings.filter((w) => w.includes('EPERM'))).toHaveLength(2);
+ expect(warnings.join('\n')).toContain('ok-dmg-app-');
+ expect(warnings.join('\n')).toContain('ok-dmg-mount-');
+ });
+});
diff --git a/.github/scripts/evaluate-smoke-alarm.mjs b/.github/scripts/evaluate-smoke-alarm.mjs
new file mode 100644
index 000000000..d4ffeb9b0
--- /dev/null
+++ b/.github/scripts/evaluate-smoke-alarm.mjs
@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+/**
+ * Aggregate alarm for a silently-broken DMG smoke gate.
+ *
+ * A per-cut alert covers a gate that BITES. It does not cover the failure mode
+ * that actually worries us: a gate that is quietly always-refusing, or a fast
+ * tier that has gone inert. Both look identical to a calm week β€” everything
+ * green, nothing shipping early, nobody notices. This evaluator watches the
+ * aggregate and pages when the pattern, rather than any single cut, is wrong.
+ *
+ * Two conditions:
+ * 1. Three consecutive fast-tier-qualified cuts whose verdict was not `pass`.
+ * One bad DMG is news; three in a row is a broken gate.
+ * 2. No fast-tier promotion in a rolling 14-day window in which at least one
+ * cut DID qualify. The tier is armed and reaching nothing.
+ *
+ * And one deliberate non-condition: if NO cut in the window qualified, nothing
+ * fires. An intentionally disarmed fast tier is not a broken one, and an alarm
+ * that screams continuously while the tier is off would train responders to
+ * ignore it β€” which would cost us the two real conditions above.
+ *
+ * Stateless. History comes from queryable workflow-run state; nothing is
+ * written back to the repository.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { appendFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+export const CONSECUTIVE_NON_PASS_THRESHOLD = 3;
+export const STALE_FAST_TIER_WINDOW_DAYS = 14;
+
+const SMOKE_JOB_NAME = "Smoke the fast-tier candidate's DMG";
+const DISPATCH_STEP_NAME = 'Dispatch promote-stable for the smoke-proven candidate';
+
+/**
+ * @param history newest-first list of `{ at, qualified, verdict, promoted }`.
+ * `qualified` β€” the cut satisfied the fast-tier predicate, so the gate was
+ * asked for an opinion. `verdict` β€” 'pass' | 'fail' | 'error' | null.
+ * `promoted` β€” a fast-tier promotion actually fired.
+ * @returns `{ alarm, reasons }` β€” `reasons` is empty when `alarm` is false.
+ */
+export function evaluateAlarm({
+ history,
+ nowMs,
+ consecutiveThreshold = CONSECUTIVE_NON_PASS_THRESHOLD,
+ windowDays = STALE_FAST_TIER_WINDOW_DAYS,
+}) {
+ const reasons = [];
+ const qualified = history.filter((h) => h.qualified);
+
+ // Condition 1 β€” leading run of non-pass verdicts among qualified cuts.
+ let streak = 0;
+ for (const cut of qualified) {
+ if (cut.verdict === 'pass') break;
+ streak += 1;
+ }
+ if (streak >= consecutiveThreshold) {
+ reasons.push(
+ `${streak} consecutive fast-tier candidates did not pass the DMG smoke (threshold ${consecutiveThreshold}) β€” the gate looks persistently broken, not merely unlucky`,
+ );
+ }
+
+ // Condition 2 β€” armed but never promoting, over a rolling window.
+ const windowStart = nowMs - windowDays * 24 * 60 * 60 * 1000;
+ const inWindow = history.filter((h) => {
+ const t = Date.parse(h.at);
+ return !Number.isNaN(t) && t >= windowStart;
+ });
+ const qualifiedInWindow = inWindow.filter((h) => h.qualified);
+ if (qualifiedInWindow.length > 0 && !inWindow.some((h) => h.promoted)) {
+ reasons.push(
+ `${qualifiedInWindow.length} cut(s) qualified for the fast tier in the last ${windowDays} days but none was promoted through it β€” the tier is armed and reaching nothing`,
+ );
+ }
+ // The disarmed case needs no branch: with nothing qualified, condition 1's
+ // streak is 0 and condition 2's guard is false, so both stay silent.
+
+ return { alarm: reasons.length > 0, reasons };
+}
+
+// --- workflow-runtime wiring (real gh boundary) ---
+
+/**
+ * Build history from the selection workflow's own run history. A run that never
+ * reached the smoke job did not qualify; a run whose smoke job ran tells us its
+ * verdict via whether the dispatch step executed or was skipped.
+ */
+export function buildHistory({ runs, jobsForRun }) {
+ return runs.map((run) => {
+ const jobs = jobsForRun(run.databaseId ?? run.id) ?? [];
+ const smoke = jobs.find((j) => j.name === SMOKE_JOB_NAME);
+ if (!smoke || smoke.conclusion === 'skipped') {
+ return { at: run.createdAt, qualified: false, verdict: null, promoted: false };
+ }
+ const dispatch = (smoke.steps ?? []).find((s) => s.name === DISPATCH_STEP_NAME);
+ const promoted = dispatch?.conclusion === 'success';
+ // The jobs API cannot distinguish `fail` from `error` β€” that lives in the
+ // job's step output, which is not queryable after the fact. `non-pass` is
+ // the honest label, and it is all either alarm condition needs.
+ return {
+ at: run.createdAt,
+ qualified: true,
+ verdict: promoted ? 'pass' : 'non-pass',
+ promoted,
+ };
+ });
+}
+
+/**
+ * Signatures of a failure that a later tick can plausibly recover from on its
+ * own. Everything else is treated as permanent and warned about, because a
+ * permanently-broken history reader makes this evaluator silently inert.
+ */
+const TRANSIENT_HISTORY_FAILURE =
+ /timeout|timed out|rate.?limit|ECONNREFUSED|ECONNRESET|ETIMEDOUT|EAI_AGAIN|socket hang up|\b5\d{2}\b|Bad Gateway|Service Unavailable/i;
+
+export function classifyHistoryFailure(message) {
+ return TRANSIENT_HISTORY_FAILURE.test(String(message ?? '')) ? '::notice::' : '::warning::';
+}
+
+/**
+ * `buildHistory` makes up to 60 serial calls through here. `execFileSync` has
+ * no socket timeout of its own, so one stalled API response would consume the
+ * job's whole 10-minute budget β€” and a timed-out job writes no GITHUB_OUTPUT,
+ * leaving `alarm` empty and silently skipping the page step. A per-call cap
+ * bounds the worst case, and the resulting ETIMEDOUT is already in the
+ * transient set.
+ */
+const GH_CALL_TIMEOUT_MS = 30_000;
+
+function ghJson(args) {
+ return JSON.parse(execFileSync('gh', args, { encoding: 'utf8', timeout: GH_CALL_TIMEOUT_MS }));
+}
+
+function main() {
+ const repo = process.env.GITHUB_REPOSITORY || 'inkeep/open-knowledge';
+ let history = [];
+ try {
+ const runs = ghJson([
+ 'run',
+ 'list',
+ '--workflow=select-beta-to-promote.yml',
+ '--limit',
+ '60',
+ '--json',
+ 'databaseId,createdAt',
+ ]);
+ history = buildHistory({
+ runs,
+ jobsForRun: (id) => ghJson(['api', `repos/${repo}/actions/runs/${id}/jobs`]).jobs,
+ });
+ } catch (err) {
+ // An unreadable history is not an alarm β€” this evaluator is itself
+ // best-effort observability, and a gh outage must not page anyone. But a
+ // PERMANENT failure (expired auth, gh dropped from the runner image, a
+ // misconfigured repo) would otherwise print the same reassuring notice on
+ // every tick forever, leaving a dead alarm looking healthy β€” which is the
+ // exact silent-failure shape this evaluator exists to detect. Split the
+ // two so only the transient class is quiet.
+ console.log(
+ `${classifyHistoryFailure(err?.message ?? String(err))}Could not read run history for the aggregate alarm: ${err?.message ?? String(err)}`,
+ );
+ }
+
+ const { alarm, reasons } = evaluateAlarm({ history, nowMs: Date.now() });
+ if (!alarm) {
+ console.log('No aggregate smoke alarm: the fast tier is either healthy or intentionally off.');
+ } else {
+ for (const reason of reasons) {
+ console.log(`::warning::Aggregate smoke alarm β€” ${reason}`);
+ }
+ }
+ if (process.env.GITHUB_OUTPUT) {
+ appendFileSync(
+ process.env.GITHUB_OUTPUT,
+ `alarm=${alarm}\nreasons=${reasons.join('; ').replace(/\r?\n/g, ' ')}\n`,
+ );
+ }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+ main();
+}
diff --git a/.github/scripts/evaluate-smoke-alarm.test.mjs b/.github/scripts/evaluate-smoke-alarm.test.mjs
new file mode 100644
index 000000000..a735dd9bd
--- /dev/null
+++ b/.github/scripts/evaluate-smoke-alarm.test.mjs
@@ -0,0 +1,256 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, test } from 'vitest';
+import {
+ buildHistory,
+ CONSECUTIVE_NON_PASS_THRESHOLD,
+ classifyHistoryFailure,
+ evaluateAlarm,
+ STALE_FAST_TIER_WINDOW_DAYS,
+} from './evaluate-smoke-alarm.mjs';
+
+const NOW = Date.parse('2026-07-28T12:00:00Z');
+const daysAgo = (n) => new Date(NOW - n * 24 * 60 * 60 * 1000).toISOString();
+
+const cut = (over = {}) => ({
+ at: daysAgo(1),
+ qualified: true,
+ verdict: 'non-pass',
+ promoted: false,
+ ...over,
+});
+const passing = (over = {}) => cut({ verdict: 'pass', promoted: true, ...over });
+const notQualified = (over = {}) =>
+ cut({ qualified: false, verdict: null, promoted: false, ...over });
+
+const run = (history) => evaluateAlarm({ history, nowMs: NOW });
+
+describe('condition 1 β€” consecutive non-pass verdicts', () => {
+ test('fires at exactly the threshold', () => {
+ const r = run([cut({ at: daysAgo(1) }), cut({ at: daysAgo(2) }), cut({ at: daysAgo(3) })]);
+ expect(r.alarm).toBe(true);
+ expect(r.reasons.join(' ')).toContain('3 consecutive fast-tier candidates');
+ expect(CONSECUTIVE_NON_PASS_THRESHOLD).toBe(3);
+ });
+
+ test('stays silent at exactly one below the threshold', () => {
+ // Two non-passes then a pass β€” bad luck, not a broken gate. A passing cut
+ // in the window also clears condition 2.
+ const r = run([cut({ at: daysAgo(1) }), cut({ at: daysAgo(2) }), passing({ at: daysAgo(3) })]);
+ expect(r.alarm).toBe(false);
+ });
+
+ test('counts only the LEADING run, so an old bad patch does not fire forever', () => {
+ const r = run([
+ passing({ at: daysAgo(1) }),
+ cut({ at: daysAgo(2) }),
+ cut({ at: daysAgo(3) }),
+ cut({ at: daysAgo(4) }),
+ ]);
+ expect(r.alarm).toBe(false);
+ });
+
+ test('non-qualifying cuts do not break the streak', () => {
+ // A quiet tick between two bad cuts is not evidence the gate recovered.
+ const r = run([
+ cut({ at: daysAgo(1) }),
+ notQualified({ at: daysAgo(2) }),
+ cut({ at: daysAgo(3) }),
+ notQualified({ at: daysAgo(4) }),
+ cut({ at: daysAgo(5) }),
+ ]);
+ expect(r.alarm).toBe(true);
+ expect(r.reasons.join(' ')).toContain('3 consecutive');
+ });
+});
+
+describe('condition 2 β€” armed but never promoting', () => {
+ test('fires when a qualifying cut sits inside the window with no promotion', () => {
+ const r = run([cut({ at: daysAgo(3) })]);
+ expect(r.alarm).toBe(true);
+ expect(r.reasons.join(' ')).toContain('armed and reaching nothing');
+ });
+
+ test('stays silent when a promotion happened inside the window', () => {
+ const r = run([cut({ at: daysAgo(3) }), passing({ at: daysAgo(5) })]);
+ expect(r.alarm).toBe(false);
+ });
+
+ test('a qualifying cut just inside the window fires; just outside does not', () => {
+ expect(STALE_FAST_TIER_WINDOW_DAYS).toBe(14);
+ const inside = run([cut({ at: daysAgo(13.9) })]);
+ expect(inside.alarm).toBe(true);
+ const outside = run([cut({ at: daysAgo(14.1) })]);
+ expect(outside.alarm).toBe(false);
+ });
+
+ test('a promotion that has aged out of the window no longer counts as healthy', () => {
+ const r = run([cut({ at: daysAgo(2) }), passing({ at: daysAgo(20) })]);
+ expect(r.alarm).toBe(true);
+ expect(r.reasons.join(' ')).toContain('armed and reaching nothing');
+ });
+});
+
+describe('a disarmed fast tier is not a broken one', () => {
+ test('no cut qualified in the window: silent', () => {
+ const r = run([notQualified({ at: daysAgo(1) }), notQualified({ at: daysAgo(5) })]);
+ expect(r.alarm).toBe(false);
+ expect(r.reasons).toEqual([]);
+ });
+
+ test('empty history β€” the shipped default β€” is silent', () => {
+ // With the fast tier unarmed the smoke job never runs, so history is empty
+ // and this evaluator must say nothing at all.
+ expect(run([])).toEqual({ alarm: false, reasons: [] });
+ });
+
+ test('a long stretch of non-qualifying cuts never fires', () => {
+ const r = run(Array.from({ length: 40 }, (_, i) => notQualified({ at: daysAgo(i * 0.3) })));
+ expect(r.alarm).toBe(false);
+ });
+});
+
+describe('both conditions can fire together', () => {
+ test('reasons name each independently', () => {
+ const r = run([cut({ at: daysAgo(1) }), cut({ at: daysAgo(2) }), cut({ at: daysAgo(3) })]);
+ expect(r.reasons).toHaveLength(2);
+ expect(r.reasons[0]).not.toBe(r.reasons[1]);
+ });
+});
+
+describe('buildHistory', () => {
+ const runs = [{ databaseId: 1, createdAt: daysAgo(1) }];
+
+ test('a run whose smoke job never existed did not qualify', () => {
+ expect(buildHistory({ runs, jobsForRun: () => [] })[0]).toMatchObject({
+ qualified: false,
+ promoted: false,
+ });
+ });
+
+ test('a skipped smoke job did not qualify β€” that is the inert default', () => {
+ const jobs = [
+ { name: "Smoke the fast-tier candidate's DMG", conclusion: 'skipped', steps: [] },
+ ];
+ expect(buildHistory({ runs, jobsForRun: () => jobs })[0].qualified).toBe(false);
+ });
+
+ test('a smoke job whose dispatch step succeeded is a pass', () => {
+ const jobs = [
+ {
+ name: "Smoke the fast-tier candidate's DMG",
+ conclusion: 'success',
+ steps: [
+ { name: 'Dispatch promote-stable for the smoke-proven candidate', conclusion: 'success' },
+ ],
+ },
+ ];
+ expect(buildHistory({ runs, jobsForRun: () => jobs })[0]).toMatchObject({
+ qualified: true,
+ verdict: 'pass',
+ promoted: true,
+ });
+ });
+
+ test('a smoke job whose dispatch step was skipped is a non-pass', () => {
+ const jobs = [
+ {
+ name: "Smoke the fast-tier candidate's DMG",
+ conclusion: 'success',
+ steps: [
+ { name: 'Dispatch promote-stable for the smoke-proven candidate', conclusion: 'skipped' },
+ ],
+ },
+ ];
+ expect(buildHistory({ runs, jobsForRun: () => jobs })[0]).toMatchObject({
+ qualified: true,
+ verdict: 'non-pass',
+ promoted: false,
+ });
+ });
+
+ test('the job and step names it keys on exist verbatim in the workflow', () => {
+ // These strings are a cross-file contract with select-beta-to-promote.yml;
+ // renaming the job there would silently zero out the history.
+ const wf = readFileSync(
+ join(
+ dirname(fileURLToPath(import.meta.url)),
+ '..',
+ 'workflows',
+ 'select-beta-to-promote.yml',
+ ),
+ 'utf8',
+ );
+ expect(wf).toContain("Smoke the fast-tier candidate's DMG");
+ expect(wf).toContain('Dispatch promote-stable for the smoke-proven candidate');
+ });
+});
+
+describe('classifyHistoryFailure', () => {
+ // A permanently-broken history reader would otherwise print the same
+ // reassuring notice every tick forever, leaving a dead alarm looking healthy
+ // β€” the exact silent-failure shape this evaluator exists to detect.
+ test.each([
+ 'request timed out',
+ 'API rate limit exceeded',
+ 'connect ECONNREFUSED 140.82.121.6:443',
+ 'read ECONNRESET',
+ 'getaddrinfo EAI_AGAIN api.github.com',
+ 'socket hang up',
+ 'HTTP 502 Bad Gateway',
+ 'HTTP 503 Service Unavailable',
+ ])('recoverable: %s β†’ notice', (msg) => {
+ expect(classifyHistoryFailure(msg)).toBe('::notice::');
+ });
+
+ test.each([
+ 'gh: command not found',
+ 'authentication failed: token expired',
+ 'HTTP 401: Bad credentials',
+ 'could not determine GITHUB_REPOSITORY',
+ 'HTTP 404: Not Found',
+ ])('permanent: %s β†’ warning', (msg) => {
+ expect(classifyHistoryFailure(msg)).toBe('::warning::');
+ });
+
+ test('an absent message is treated as permanent, not quietly ignored', () => {
+ expect(classifyHistoryFailure(undefined)).toBe('::warning::');
+ expect(classifyHistoryFailure('')).toBe('::warning::');
+ });
+});
+
+describe('buildHistory run-id fallback', () => {
+ test('falls back to run.id when databaseId is absent', () => {
+ // `gh run list --json databaseId` supplies databaseId; the REST shape uses
+ // `id`. The fallback keeps both readable β€” pinned so it is not tidied away.
+ const seen = [];
+ buildHistory({
+ runs: [{ id: 42, createdAt: daysAgo(1) }],
+ jobsForRun: (id) => {
+ seen.push(id);
+ return [];
+ },
+ });
+ expect(seen).toEqual([42]);
+ });
+
+ test('prefers databaseId when both are present', () => {
+ const seen = [];
+ buildHistory({
+ runs: [{ databaseId: 7, id: 42, createdAt: daysAgo(1) }],
+ jobsForRun: (id) => {
+ seen.push(id);
+ return [];
+ },
+ });
+ expect(seen).toEqual([7]);
+ });
+
+ test('a jobsForRun returning null does not throw', () => {
+ expect(
+ buildHistory({ runs: [{ databaseId: 1, createdAt: daysAgo(1) }], jobsForRun: () => null })[0]
+ .qualified,
+ ).toBe(false);
+ });
+});
diff --git a/.github/scripts/release-cascade-shape.test.mjs b/.github/scripts/release-cascade-shape.test.mjs
new file mode 100644
index 000000000..69a0fd6b3
--- /dev/null
+++ b/.github/scripts/release-cascade-shape.test.mjs
@@ -0,0 +1,260 @@
+/**
+ * Adversarial proof that the release gates bite, plus the ordering and payload
+ * invariants a later edit is most likely to break silently.
+ *
+ * GitHub Actions cannot be executed locally, so the ordering assertions parse
+ * the workflow's flat step list and compare positions. That is the highest
+ * fidelity available for "the gate runs before the thing it gates", and it is
+ * precisely the invariant a well-meaning reorder would destroy without any
+ * test noticing.
+ */
+
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterAll, describe, expect, test } from 'vitest';
+import { buildDiscordPayload, buildSlackPayload } from './build-smoke-alert-payload.mjs';
+import { selectPromotion } from './select-beta-to-promote.mjs';
+import { smokePackagedDmg, VERDICT } from './smoke-packaged-dmg.mjs';
+
+const WORKFLOWS = join(dirname(fileURLToPath(import.meta.url)), '..', 'workflows');
+const read = (name) => readFileSync(join(WORKFLOWS, name), 'utf8');
+const desktopRelease = read('desktop-release.yml');
+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.
+ */
+function stepNames(source) {
+ const names = [...source.matchAll(/^ {6}- name: (.+)$/gm)].map((m) => m[1].trim());
+ if (names.length < 5) {
+ throw new Error(
+ `step-name parse found only ${names.length} steps; the shape must have changed`,
+ );
+ }
+ return names;
+}
+
+const indexOfStep = (names, needle) => names.findIndex((n) => n.includes(needle));
+
+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'),
+ );
+ });
+
+ test('the smoke gate runs before the draft is promoted to published', () => {
+ const smoke = indexOfStep(names, 'Smoke the packaged DMG');
+ const promote = indexOfStep(names, 'Promote draft release to published');
+ expect(smoke).toBeGreaterThan(-1);
+ expect(promote).toBeGreaterThan(-1);
+ expect(smoke).toBeLessThan(promote);
+ });
+
+ test('the smoke gate runs before the publish-stable dispatch, so npm cannot move first', () => {
+ const smoke = indexOfStep(names, 'Smoke the packaged DMG');
+ const npm = indexOfStep(names, 'Trigger release.yml to publish stable to npm');
+ expect(npm).toBeGreaterThan(-1);
+ expect(smoke).toBeLessThan(npm);
+ });
+
+ test('the smoke gate runs before both release announcements', () => {
+ const smoke = indexOfStep(names, 'Smoke the packaged DMG');
+ expect(smoke).toBeLessThan(indexOfStep(names, 'Announce stable release to Slack'));
+ expect(smoke).toBeLessThan(indexOfStep(names, 'Announce stable release to Discord'));
+ });
+
+ test('nothing downstream of the gate opts out of the implicit success() guard', () => {
+ // A downstream step carrying `if: always()` would run even after the gate
+ // refused β€” which is exactly how a gate stops gating.
+ const afterGate = desktopRelease.slice(
+ desktopRelease.indexOf('- name: Smoke the packaged DMG'),
+ );
+ const shipping = afterGate.slice(
+ 0,
+ afterGate.indexOf('- name: Alert on a blocked release'), // failure-conditioned by design
+ );
+ expect(shipping).not.toContain('if: always()');
+ expect(shipping).not.toContain('!cancelled()');
+ });
+
+ test('every shipping step with an explicit if: spells success() itself', () => {
+ // The subtler sibling of the test above, and the one that matters more.
+ // Actions injects the implicit `success()` ONLY on steps with no `if:`;
+ // 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.
+ 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.
+ const shippingConditions = conditions.filter(
+ (c) => c !== "steps.channel.outputs.channel == 'latest'",
+ );
+ expect(shippingConditions.length).toBeGreaterThan(0);
+ for (const condition of shippingConditions) {
+ expect(condition, `shipping step condition lacks success(): ${condition}`).toContain(
+ 'success()',
+ );
+ }
+ });
+});
+
+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"');
+ expect(desktopRelease).toContain('event_type: "publish-stable"');
+ });
+
+ test('the event type is exactly what release.yml listens for', () => {
+ expect(releaseYml).toContain('types: [publish-stable]');
+ expect(desktopRelease).toContain('{event_type: "publish-stable", client_payload:');
+ });
+
+ test('the payload carries the same three field names release.yml reads', () => {
+ const dispatch = desktopRelease.slice(
+ desktopRelease.indexOf('- name: Trigger release.yml to publish stable to npm'),
+ );
+ const payload = dispatch.slice(dispatch.indexOf('jq -nc'), dispatch.indexOf('gh api -X POST'));
+ for (const field of ['ref: $ref', 'version: $version', 'dispatched_by: $by']) {
+ expect(payload).toContain(field);
+ }
+ // And release.yml still reads each of them.
+ expect(releaseYml).toContain('github.event.client_payload.ref');
+ expect(releaseYml).toContain('github.event.client_payload.version');
+ expect(releaseYml).toContain('github.event.client_payload.dispatched_by');
+ });
+
+ test('the dispatch is gated so beta cuts and manual re-runs never publish npm', () => {
+ const dispatch = desktopRelease.slice(
+ 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("github.event_name != 'workflow_dispatch'");
+ });
+});
+
+describe('a non-pass verdict keeps a beta off the fast tier', () => {
+ const meta = {
+ isDraft: false,
+ publishedAt: '2026-07-28T11:00:00Z', // 1h old β€” under-soaked
+ assets: [{ name: 'x.dmg' }, { name: 'beta-mac.yml' }],
+ };
+ const soaked = { ...meta, publishedAt: '2026-07-25T11:00:00Z' };
+ const NOW = Date.parse('2026-07-28T12:00:00Z');
+
+ const decide = (smokeVerdict) =>
+ selectPromotion({
+ betaTags: ['v1.0.0-beta.2', 'v1.0.0-beta.1'],
+ isAlreadyShipped: () => false,
+ fetchReleaseMeta: (t) => (t === 'v1.0.0-beta.2' ? meta : soaked),
+ soakSeconds: 86400,
+ nowMs: NOW,
+ qualifiesForFastTier: () => true,
+ smokeBeta: () => smokeVerdict,
+ });
+
+ test('pass promotes early; fail and error both fall back to the 24h tier', () => {
+ expect(decide('pass')).toEqual({ kind: 'select', target: 'v1.0.0-beta.2', tier: 'fast' });
+ for (const bad of ['fail', 'error']) {
+ expect(decide(bad)).toEqual({ kind: 'select', target: 'v1.0.0-beta.1', tier: 'soak' });
+ }
+ });
+});
+
+describe('a deliberately broken DMG never reads as a pass', () => {
+ const scratch = mkdtempSync(join(tmpdir(), 'ok-broken-dmg-'));
+ afterAll(() => rmSync(scratch, { recursive: true, force: true }));
+
+ test('a file that is named .dmg but is not one yields a non-pass verdict', async () => {
+ // No mocks anywhere below this line: the real driver, the real mount
+ // helper, the real filesystem. On macOS hdiutil refuses the garbage file;
+ // on Linux hdiutil does not exist. Both are infrastructure, so both are
+ // `error` β€” and the point of the test is that neither is ever `pass`.
+ const fake = join(scratch, 'NotReallyOpenKnowledge.dmg');
+ writeFileSync(fake, 'this is not a disk image\n');
+
+ const result = await smokePackagedDmg(fake, {
+ // Fail loud if the runner is somehow reached β€” a broken DMG must never
+ // get that far.
+ runPlaywright: async () => {
+ throw new Error('the Playwright runner must not be reached for a broken DMG');
+ },
+ });
+
+ expect(result.verdict).not.toBe(VERDICT.pass);
+ expect(result.verdict).toBe(VERDICT.error);
+ expect(result.reason).toContain('could not prepare the DMG');
+ });
+});
+
+describe('a forced smoke failure pages both channels, not just an annotation', () => {
+ const forced = {
+ tag: 'v9.9.9',
+ verdict: 'fail',
+ reason: 'forced failure',
+ runUrl: 'https://example.test/run/1',
+ };
+
+ test('both payloads are produced and both name the blocked release', () => {
+ const slack = buildSlackPayload(forced);
+ const discord = buildDiscordPayload(forced);
+ expect(slack.blocks.length).toBeGreaterThan(0);
+ expect(discord.embeds.length).toBeGreaterThan(0);
+ for (const s of [JSON.stringify(slack), JSON.stringify(discord)]) {
+ expect(s).toContain('RELEASE BLOCKED');
+ expect(s).toContain('v9.9.9');
+ }
+ });
+
+ test('the workflow posts to both webhooks in addition to annotating', () => {
+ const step = desktopRelease.slice(
+ desktopRelease.indexOf('- name: Alert on a blocked release'),
+ desktopRelease.indexOf('- name: Warn on stuck draft'),
+ );
+ expect(step).toContain('post slack');
+ expect(step).toContain('post discord');
+ expect(step).toContain('::error::RELEASE BLOCKED');
+ });
+});
+
+describe('the stable gate does not touch the beta cadence', () => {
+ const scoped = (stepHeader) => {
+ const at = desktopRelease.indexOf(stepHeader);
+ expect(at).toBeGreaterThan(-1);
+ return desktopRelease.slice(at, at + 500);
+ };
+
+ test('the smoke gate is stable-only', () => {
+ // Betas flow through this same job. Gating them here would add 5-15 min to
+ // every cadence cut and let a bad DMG block the cadence itself; the beta
+ // equivalent is the selection-time gate, which runs after publication.
+ expect(scoped('- name: Smoke the packaged DMG (FR5b)')).toContain(
+ "if: steps.channel.outputs.channel == 'latest'",
+ );
+ });
+
+ test('the alert is stable-only too, so a beta hiccup does not page', () => {
+ expect(scoped('- name: Alert on a blocked release (FR5c)')).toContain(
+ "if: failure() && steps.channel.outputs.channel == 'latest'",
+ );
+ });
+
+ test('the beta path keeps its existing stuck-draft warning', () => {
+ const warn = scoped('- name: Warn on stuck draft');
+ expect(warn).toContain('if: failure()');
+ expect(warn).not.toContain("channel == 'latest'");
+ });
+});
diff --git a/.github/scripts/select-beta-to-promote.mjs b/.github/scripts/select-beta-to-promote.mjs
index 1cba5bef3..6c5e19b8a 100644
--- a/.github/scripts/select-beta-to-promote.mjs
+++ b/.github/scripts/select-beta-to-promote.mjs
@@ -23,9 +23,9 @@
// null for 404 and throwing for everything else; selectPromotion lets the throw
// propagate so main() can exit non-zero.
-import { execFileSync, spawnSync } from "node:child_process";
-import { appendFileSync } from "node:fs";
-import { pathToFileURL } from "node:url";
+import { execFileSync, spawnSync } from 'node:child_process';
+import { appendFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
const BETA_TAG_RE = /^v\d+\.\d+\.\d+-beta\.\d+$/;
const STABLE_TAG_RE = /^v\d+\.\d+\.\d+$/;
@@ -36,21 +36,24 @@ const STABLE_TAG_RE = /^v\d+\.\d+\.\d+$/;
// stable tags and any non-conforming ref.
export function parseBetaTags(rawTagOutput) {
return rawTagOutput
- .split("\n")
+ .split('\n')
.map((s) => s.trim())
.filter((s) => BETA_TAG_RE.test(s));
}
function isFullyCut(meta) {
const assets = Array.isArray(meta.assets) ? meta.assets : [];
- const hasDmg = assets.some((a) => typeof a.name === "string" && a.name.endsWith(".dmg"));
- const hasManifest = assets.some((a) => typeof a.name === "string" && a.name.endsWith("-mac.yml"));
+ const hasDmg = assets.some((a) => typeof a.name === 'string' && a.name.endsWith('.dmg'));
+ const hasManifest = assets.some((a) => typeof a.name === 'string' && a.name.endsWith('-mac.yml'));
return meta.isDraft !== true && Boolean(meta.publishedAt) && hasDmg && hasManifest;
}
// Walk betaTags newest -> oldest and return the selection decision:
-// { kind: "select", target } -> dispatch promote-stable for `target`
-// { kind: "none" } -> nothing eligible right now
+// { kind: "select", target, tier } -> dispatch promote-stable for `target`
+// { kind: "none" } -> nothing eligible right now
+// `tier` is "soak" for the 24h path and "fast" for a DMG-smoke-proven early
+// promotion.
+//
// Selects the NEWEST beta that is unshipped + fully cut + soaked >= soakSeconds.
// A fresher head that is under-soaked or not-yet-cut is skipped in favor of the
// previous soaked beta. The descent STOPS at the first already-shipped beta (its
@@ -59,22 +62,70 @@ function isFullyCut(meta) {
// promote-stable derives it from the changeset delta over the latest stable.
// Propagates any throw from fetchReleaseMeta (a non-404 infra error) instead of
// skipping the candidate.
-export function selectPromotion({ betaTags, isAlreadyShipped, fetchReleaseMeta, soakSeconds, nowMs }) {
+//
+// FAST TIER (FR5a), OFF BY DEFAULT. `qualifiesForFastTier` defaults to "nothing
+// qualifies", which makes the under-soaked branch below fall through to the same
+// `continue` this function has always used β€” so with no predicate supplied the
+// decision is byte-for-byte what it is today and `smokeBeta` is never called.
+// When a predicate IS supplied, an under-soaked candidate is promoted early only
+// if its DMG smoke returns "pass". "fail" and "error" both refuse the fast tier
+// and leave the 24h outcome exactly as it would have been, and neither ever
+// fails the job β€” this evaluator must never block a release.
+export function selectPromotion({
+ betaTags,
+ isAlreadyShipped,
+ fetchReleaseMeta,
+ soakSeconds,
+ nowMs,
+ qualifiesForFastTier = () => false,
+ smokeBeta = null,
+ log = () => {},
+}) {
const soakMs = soakSeconds * 1000;
for (const beta of betaTags) {
if (isAlreadyShipped(beta)) {
// This beta's commit is already in the latest stable; every older beta is
// too. Nothing newer than this is eligible below, so stop.
- return { kind: "none" };
+ return { kind: 'none' };
}
const meta = fetchReleaseMeta(beta); // null === 404 (no release yet); throws on infra error
if (meta === null) continue;
if (!isFullyCut(meta)) continue;
const ageMs = nowMs - Date.parse(meta.publishedAt);
- if (Number.isNaN(ageMs) || ageMs < soakMs) continue;
- return { kind: "select", target: beta };
+ if (!Number.isNaN(ageMs) && ageMs >= soakMs) {
+ return { kind: 'select', target: beta, tier: 'soak' };
+ }
+ // Under-soaked (or unparseable publish date). The fast tier is the only way
+ // this beta can be selected; everything below is inert unless armed.
+ if (smokeBeta && qualifiesForFastTier(beta, meta)) {
+ const verdict = evaluateSmoke(beta, smokeBeta, log);
+ if (verdict === 'pass') {
+ return { kind: 'select', target: beta, tier: 'fast' };
+ }
+ // Refuse the fast tier and keep descending, which is exactly what this
+ // loop did before the fast tier existed.
+ log(
+ verdict === 'fail'
+ ? `::warning::Fast tier REFUSED for ${beta}: its DMG failed the smoke subset. Falling back to the 24h tier.`
+ : `::warning::Fast tier REFUSED for ${beta}: the DMG smoke hit an infrastructure error and never reached a verdict. Falling back to the 24h tier.`,
+ );
+ }
+ }
+ return { kind: 'none' };
+}
+
+// A smoke outcome can never fail this job (FR5a: the gate must never block a
+// release), so a thrown smoke is folded into the `error` verdict rather than
+// propagated. This is deliberately unlike fetchReleaseMeta, whose non-404
+// throws MUST propagate β€” that one decides whether a beta is shippable at all.
+function evaluateSmoke(beta, smokeBeta, log) {
+ try {
+ const verdict = smokeBeta(beta);
+ return verdict === 'pass' || verdict === 'fail' ? verdict : 'error';
+ } catch (err) {
+ log(`::warning::DMG smoke threw for ${beta}: ${err?.message ?? String(err)}`);
+ return 'error';
}
- return { kind: "none" };
}
// --- workflow-runtime wiring (real git / gh boundary) ---
@@ -85,31 +136,35 @@ export function selectPromotion({ betaTags, isAlreadyShipped, fetchReleaseMeta,
// longer maps 1:1 to a stable version, so "is this beta already released" is
// "is its commit contained in the latest stable".
function resolveLatestStableSha() {
- const out = execFileSync("git", ["tag", "--list", "v*", "--sort=-version:refname"], { encoding: "utf8" });
- for (const line of out.split("\n")) {
+ const out = execFileSync('git', ['tag', '--list', 'v*', '--sort=-version:refname'], {
+ encoding: 'utf8',
+ });
+ for (const line of out.split('\n')) {
const t = line.trim();
if (STABLE_TAG_RE.test(t)) {
- return execFileSync("git", ["rev-parse", "--verify", `${t}^{commit}`], { encoding: "utf8" }).trim();
+ return execFileSync('git', ['rev-parse', '--verify', `${t}^{commit}`], {
+ encoding: 'utf8',
+ }).trim();
}
}
- return "";
+ return '';
}
function makeRealIsAlreadyShipped(latestStableSha) {
return (betaTag) => {
if (!latestStableSha) return false; // no stable yet -> nothing is shipped
- const betaSha = execFileSync("git", ["rev-parse", "--verify", `${betaTag}^{commit}`], {
- encoding: "utf8",
+ const betaSha = execFileSync('git', ['rev-parse', '--verify', `${betaTag}^{commit}`], {
+ encoding: 'utf8',
}).trim();
// Distinguish a clean "not an ancestor" (exit 1) from an infra failure (any
// other non-zero), which must fail loud rather than read as "not shipped".
- const res = spawnSync("git", ["merge-base", "--is-ancestor", betaSha, latestStableSha], {
- encoding: "utf8",
+ const res = spawnSync('git', ['merge-base', '--is-ancestor', betaSha, latestStableSha], {
+ encoding: 'utf8',
});
if (res.status === 0) return true;
if (res.status === 1) return false;
throw new Error(
- `git merge-base --is-ancestor ${betaSha} ${latestStableSha} failed (exit ${res.status}): ${String(res.stderr || "").trim()}`,
+ `git merge-base --is-ancestor ${betaSha} ${latestStableSha} failed (exit ${res.status}): ${String(res.stderr || '').trim()}`,
);
};
}
@@ -120,14 +175,18 @@ function makeRealIsAlreadyShipped(latestStableSha) {
// string-match the 404 signature and rethrow everything else (fail loud).
function realFetchReleaseMeta(tag) {
try {
- const out = execFileSync("gh", ["release", "view", tag, "--json", "isDraft,publishedAt,assets"], {
- encoding: "utf8",
- stdio: ["ignore", "pipe", "pipe"],
- });
+ const out = execFileSync(
+ 'gh',
+ ['release', 'view', tag, '--json', 'isDraft,publishedAt,assets'],
+ {
+ encoding: 'utf8',
+ stdio: ['ignore', 'pipe', 'pipe'],
+ },
+ );
const j = JSON.parse(out);
return { isDraft: j.isDraft, publishedAt: j.publishedAt || null, assets: j.assets || [] };
} catch (err) {
- const stderr = String(err?.stderr || err?.message || "");
+ const stderr = String(err?.stderr || err?.message || '');
if (/release not found|not found|HTTP 404|could not find/i.test(stderr)) {
return null;
}
@@ -136,9 +195,9 @@ function realFetchReleaseMeta(tag) {
}
function main() {
- const soakSeconds = Number(process.env.SOAK_SECONDS || "86400");
- const rawTags = execFileSync("git", ["tag", "--list", "v*-beta.*", "--sort=-version:refname"], {
- encoding: "utf8",
+ const soakSeconds = Number(process.env.SOAK_SECONDS || '86400');
+ const rawTags = execFileSync('git', ['tag', '--list', 'v*-beta.*', '--sort=-version:refname'], {
+ encoding: 'utf8',
});
const betaTags = parseBetaTags(rawTags);
const latestStableSha = resolveLatestStableSha();
@@ -160,16 +219,30 @@ function main() {
process.exit(1);
}
- let target = "";
- if (result.kind === "select") {
+ let target = '';
+ let tier = '';
+ if (result.kind === 'select') {
target = result.target;
- console.log(`::notice::Eligible: ${target} (unshipped + fully cut + soaked >= ${soakSeconds}s).`);
+ tier = result.tier;
+ console.log(
+ `::notice::Eligible: ${target} (unshipped + fully cut + soaked >= ${soakSeconds}s).`,
+ );
} else {
- console.log("No-op: no beta is currently eligible (need unshipped + fully cut + soaked >= 24h).");
+ console.log(
+ 'No-op: no beta is currently eligible (need unshipped + fully cut + soaked >= 24h).',
+ );
}
if (process.env.GITHUB_OUTPUT) {
- appendFileSync(process.env.GITHUB_OUTPUT, `target=${target}\n`);
+ // `fast_tier_candidate` is the seam the macOS smoke leg keys off. Nothing
+ // populates it today: `main()` supplies no fast-tier predicate, so
+ // selectPromotion never reports the fast tier and the leg never runs. That
+ // is the whole of the build-but-do-not-arm posture β€” arming is a documented
+ // operator step in RELEASES.md, not a side effect of merging this.
+ appendFileSync(
+ process.env.GITHUB_OUTPUT,
+ `target=${target}\ntier=${tier}\nfast_tier_candidate=\n`,
+ );
}
}
diff --git a/.github/scripts/select-beta-to-promote.test.mjs b/.github/scripts/select-beta-to-promote.test.mjs
index 22ed79adb..330860b4a 100644
--- a/.github/scripts/select-beta-to-promote.test.mjs
+++ b/.github/scripts/select-beta-to-promote.test.mjs
@@ -52,7 +52,7 @@ describe('selectPromotion', () => {
'v0.10.0-beta.5': meta({ publishedAt: SOAKED }),
}),
});
- expect(r).toEqual({ kind: 'select', target: 'v0.10.0-beta.5' });
+ expect(r).toEqual({ kind: 'select', target: 'v0.10.0-beta.5', tier: 'soak' });
});
test('selects the head when the head itself is soaked', () => {
@@ -63,7 +63,7 @@ describe('selectPromotion', () => {
'v0.10.0-beta.5': meta({ publishedAt: SOAKED }),
}),
});
- expect(r).toEqual({ kind: 'select', target: 'v0.10.0-beta.6' });
+ expect(r).toEqual({ kind: 'select', target: 'v0.10.0-beta.6', tier: 'soak' });
});
test('selects the newest soaked UNSHIPPED beta, even across a version boundary', () => {
@@ -78,7 +78,7 @@ describe('selectPromotion', () => {
'v0.30.1-beta.8': meta({ publishedAt: SOAKED }),
}),
});
- expect(r).toEqual({ kind: 'select', target: 'v0.31.0-beta.0' });
+ expect(r).toEqual({ kind: 'select', target: 'v0.31.0-beta.0', tier: 'soak' });
});
test('stops at the first already-shipped beta and never reaches an older cycle', () => {
@@ -100,7 +100,7 @@ describe('selectPromotion', () => {
'v0.10.0-beta.5': meta({ publishedAt: SOAKED }),
}),
});
- expect(r).toEqual({ kind: 'select', target: 'v0.10.0-beta.5' });
+ expect(r).toEqual({ kind: 'select', target: 'v0.10.0-beta.5', tier: 'soak' });
});
test('skips a head missing the DMG asset', () => {
@@ -159,3 +159,106 @@ describe('selectPromotion', () => {
).toThrow(/infra error/);
});
});
+
+describe('fast tier (FR5a) β€” DMG-smoke-gated early promotion', () => {
+ // Two under-soaked betas over one soaked one. Without the fast tier the
+ // evaluator descends past both and picks beta.4; with it, an under-soaked
+ // beta can be promoted early, but only on a passing DMG smoke.
+ const TAGS = ['v0.10.0-beta.6', 'v0.10.0-beta.5', 'v0.10.0-beta.4'];
+ const metas = fetcher({
+ 'v0.10.0-beta.6': meta({ publishedAt: FRESH }),
+ 'v0.10.0-beta.5': meta({ publishedAt: FRESH }),
+ 'v0.10.0-beta.4': meta({ publishedAt: SOAKED }),
+ });
+ const fastTierOn = () => true;
+
+ function run(over = {}) {
+ const logs = [];
+ const smokeCalls = [];
+ const result = select({
+ betaTags: TAGS,
+ fetchReleaseMeta: metas,
+ log: (m) => logs.push(m),
+ ...over,
+ smokeBeta: over.smokeBeta
+ ? (tag) => {
+ smokeCalls.push(tag);
+ return over.smokeBeta(tag);
+ }
+ : undefined,
+ });
+ return { result, logs, smokeCalls };
+ }
+
+ test('is inert by default: same selection as today, and the smoke is never invoked', () => {
+ const { result, smokeCalls } = run({ smokeBeta: () => 'pass' });
+ // No predicate supplied -> nothing qualifies -> descends to the soaked beta.
+ expect(result).toEqual({ kind: 'select', target: 'v0.10.0-beta.4', tier: 'soak' });
+ expect(smokeCalls).toEqual([]);
+ });
+
+ test('a passing DMG smoke promotes the under-soaked head on the fast tier', () => {
+ const { result, smokeCalls } = run({
+ qualifiesForFastTier: fastTierOn,
+ smokeBeta: () => 'pass',
+ });
+ expect(result).toEqual({ kind: 'select', target: 'v0.10.0-beta.6', tier: 'fast' });
+ expect(smokeCalls).toEqual(['v0.10.0-beta.6']);
+ });
+
+ test('a failing DMG smoke refuses the fast tier and leaves the 24h outcome untouched', () => {
+ const { result, logs } = run({
+ qualifiesForFastTier: fastTierOn,
+ smokeBeta: () => 'fail',
+ });
+ const withoutFastTier = select({ betaTags: TAGS, fetchReleaseMeta: metas });
+ expect(result).toEqual(withoutFastTier);
+ expect(result).toEqual({ kind: 'select', target: 'v0.10.0-beta.4', tier: 'soak' });
+ expect(logs.join('\n')).toContain('failed the smoke subset');
+ });
+
+ test('an infrastructure error refuses the fast tier and is distinguishable from a fail', () => {
+ const failLogs = run({ qualifiesForFastTier: fastTierOn, smokeBeta: () => 'fail' }).logs;
+ const errorLogs = run({ qualifiesForFastTier: fastTierOn, smokeBeta: () => 'error' }).logs;
+ expect(errorLogs.join('\n')).toContain('infrastructure error');
+ expect(errorLogs.join('\n')).not.toContain('failed the smoke subset');
+ expect(failLogs.join('\n')).not.toContain('infrastructure error');
+ });
+
+ test('a thrown smoke never fails the job β€” it degrades to an error refusal', () => {
+ // FR5a: the selection gate must never block a release. Unlike
+ // fetchReleaseMeta, whose non-404 throws must propagate.
+ const { result, logs } = run({
+ qualifiesForFastTier: fastTierOn,
+ smokeBeta: () => {
+ throw new Error('runner exploded');
+ },
+ });
+ expect(result).toEqual({ kind: 'select', target: 'v0.10.0-beta.4', tier: 'soak' });
+ expect(logs.join('\n')).toContain('runner exploded');
+ });
+
+ test('an unrecognised verdict is treated as an error, never as a pass', () => {
+ const { result } = run({ qualifiesForFastTier: fastTierOn, smokeBeta: () => 'probably fine' });
+ expect(result.tier).toBe('soak');
+ });
+
+ test('the predicate can qualify one beta and not another', () => {
+ const { result, smokeCalls } = run({
+ qualifiesForFastTier: (tag) => tag === 'v0.10.0-beta.5',
+ smokeBeta: () => 'pass',
+ });
+ expect(result).toEqual({ kind: 'select', target: 'v0.10.0-beta.5', tier: 'fast' });
+ expect(smokeCalls).toEqual(['v0.10.0-beta.5']);
+ });
+
+ test('the fast tier never reaches back across an already-shipped boundary', () => {
+ const { result, smokeCalls } = run({
+ isAlreadyShipped: shippedIn('v0.10.0-beta.6'),
+ qualifiesForFastTier: fastTierOn,
+ smokeBeta: () => 'pass',
+ });
+ expect(result).toEqual({ kind: 'none' });
+ expect(smokeCalls).toEqual([]);
+ });
+});
diff --git a/.github/scripts/smoke-packaged-dmg.mjs b/.github/scripts/smoke-packaged-dmg.mjs
new file mode 100644
index 000000000..78c24750a
--- /dev/null
+++ b/.github/scripts/smoke-packaged-dmg.mjs
@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * Packaged-DMG smoke driver β€” the shared engine behind both release gates.
+ *
+ * Mounts a `.dmg`, copies the `.app` out, runs the packaged Playwright subset
+ * against the copy, and reports a TRI-STATE verdict:
+ *
+ * pass β€” the subset ran and every test passed.
+ * fail β€” the subset ran and the app genuinely misbehaved.
+ * error β€” infrastructure: the DMG would not mount, the runner would not
+ * start, the report was unreadable, or nothing actually executed.
+ *
+ * The three-way split is the whole design. Collapsing `error` into `fail` lets
+ * a runner outage masquerade as a product verdict; collapsing it into a hard
+ * job failure would block the release path the selection gate is required
+ * never to block. Callers decide what each state means for them; the driver
+ * only decides which one is true.
+ *
+ * The zero-executed rule is the adversarial core: a DMG so broken that Electron
+ * never launches produces an all-skipped run, and an all-skipped run reads
+ * green to anyone counting failures. That is exactly the silent-failure shape
+ * these gates exist to close, so zero executed is `error`, never `pass`.
+ *
+ * Usage: node .github/scripts/smoke-packaged-dmg.mjs <path-to.dmg>
+ */
+
+import { spawn } from 'node:child_process';
+import { appendFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { withMountedDmg } from './dmg-mount.mjs';
+
+export const VERDICT = {
+ pass: 'pass',
+ fail: 'fail',
+ error: 'error',
+};
+
+export const EXIT_CODES = {
+ [VERDICT.pass]: 0,
+ [VERDICT.fail]: 1,
+ [VERDICT.error]: 2,
+};
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const DESKTOP_DIR = resolve(SCRIPT_DIR, '..', '..', 'packages', 'desktop');
+const PACKAGED_CONFIG = 'playwright.packaged.config.ts';
+const PACKAGED_REPORT = join('test-results', 'desktop-smoke-packaged-results.json');
+
+/**
+ * Pure verdict function. `report` is the parsed Playwright JSON report, or null
+ * when it could not be read or parsed.
+ */
+export function classifyRun({ runExitCode, report, runnerError }) {
+ if (runnerError) {
+ return {
+ verdict: VERDICT.error,
+ reason: `the Playwright runner could not be started: ${runnerError}`,
+ };
+ }
+ if (report === null || report === undefined) {
+ return {
+ verdict: VERDICT.error,
+ reason:
+ 'the Playwright JSON report was missing or unparseable, so no verdict could be read from the run',
+ };
+ }
+ const stats = report.stats ?? {};
+ const expected = stats.expected ?? 0;
+ const unexpected = stats.unexpected ?? 0;
+ const flaky = stats.flaky ?? 0;
+ const skipped = stats.skipped ?? 0;
+ const executed = expected + unexpected + flaky;
+
+ if (executed === 0) {
+ return {
+ verdict: VERDICT.error,
+ reason: `no smoke test actually executed (${skipped} skipped) β€” an all-skipped run proves nothing about the DMG and must never read as a pass`,
+ };
+ }
+ if (unexpected > 0) {
+ return {
+ verdict: VERDICT.fail,
+ reason: `${unexpected} of ${executed} executed smoke tests failed against the packaged app`,
+ };
+ }
+ if (runExitCode !== 0) {
+ return {
+ verdict: VERDICT.error,
+ reason: `the Playwright runner exited ${runExitCode} with no failing test β€” treat as an infrastructure problem, not an app verdict`,
+ };
+ }
+ return {
+ verdict: VERDICT.pass,
+ reason: `all ${executed} executed smoke tests passed against the packaged app (${flaky} flaky, ${skipped} skipped)`,
+ };
+}
+
+/** GitHub annotation for a verdict. `fail` and `error` must read differently. */
+export function annotationFor(verdict, reason, dmgPath) {
+ if (verdict === VERDICT.pass) {
+ return `::notice::DMG smoke PASSED for ${dmgPath} β€” ${reason}`;
+ }
+ if (verdict === VERDICT.fail) {
+ return `::warning::DMG smoke FAILED (the app misbehaved) for ${dmgPath} β€” ${reason}`;
+ }
+ return `::warning::DMG smoke ERRORED (infrastructure, not an app verdict) for ${dmgPath} β€” ${reason}`;
+}
+
+/**
+ * Publish the verdict. Writes `verdict=` / `reason=` to the step-output file
+ * when GITHUB_OUTPUT is set; otherwise echoes the same pair to stdout so a
+ * local run is still readable.
+ */
+export function publishVerdict({ verdict, reason }, deps = {}) {
+ const env = deps.env ?? process.env;
+ const appendFile = deps.appendFileSync ?? appendFileSync;
+ const write = deps.writeStream ?? ((s) => process.stdout.write(s));
+ // Newlines would corrupt the `key=value` step-output format, and every reason
+ // this driver produces is a single sentence.
+ const flat = String(reason).replace(/\r?\n/g, ' ');
+ if (env.GITHUB_OUTPUT) {
+ appendFile(env.GITHUB_OUTPUT, `verdict=${verdict}\nreason=${flat}\n`);
+ } else {
+ write(`verdict=${verdict}\nreason=${flat}\n`);
+ }
+}
+
+async function defaultRunPlaywright(appPath, deps = {}) {
+ const spawnImpl = deps.spawn ?? spawn;
+ return await new Promise((resolvePromise) => {
+ const child = spawnImpl('pnpm', ['exec', 'playwright', 'test', '--config', PACKAGED_CONFIG], {
+ cwd: DESKTOP_DIR,
+ stdio: 'inherit',
+ env: {
+ ...process.env,
+ OK_DESKTOP_PACKAGED_APP: appPath,
+ OK_DESKTOP_E2E_SMOKE: '1',
+ },
+ });
+ child.on('exit', (code) => resolvePromise({ exitCode: code ?? 1 }));
+ child.on('error', (err) => resolvePromise({ exitCode: 1, runnerError: err.message }));
+ });
+}
+
+async function defaultReadReport(deps = {}) {
+ const warn = deps.warn ?? ((msg) => process.stderr.write(`[smoke-packaged-dmg] ${msg}\n`));
+ try {
+ return JSON.parse(await readFile(join(DESKTOP_DIR, PACKAGED_REPORT), 'utf-8'));
+ } catch (err) {
+ // Non-fatal β€” `classifyRun` maps null to an `error` verdict. But four very
+ // different causes collapse into that one generic reason (ENOENT: the
+ // runner never launched; SyntaxError: the report was truncated; EPERM:
+ // permissions; shape mismatch), and each wants a different response. The
+ // responder reading a RELEASE BLOCKED page sees only the generic reason,
+ // so this line is the only place the distinction survives.
+ warn(`could not read ${PACKAGED_REPORT}: ${err?.message ?? String(err)}`);
+ return null;
+ }
+}
+
+/**
+ * Mount, run, classify. Returns `{verdict, reason}`; never throws for a
+ * mount/run failure β€” those become `error` verdicts.
+ */
+export async function smokePackagedDmg(dmgPath, deps = {}) {
+ const withMount = deps.withMountedDmg ?? withMountedDmg;
+ const runPlaywright = deps.runPlaywright ?? ((appPath) => defaultRunPlaywright(appPath, deps));
+ const readReport = deps.readReport ?? (() => defaultReadReport(deps));
+
+ try {
+ return await withMount(
+ dmgPath,
+ async (appPath) => {
+ const { exitCode, runnerError } = await runPlaywright(appPath);
+ const report = await readReport(appPath);
+ return classifyRun({ runExitCode: exitCode, report, runnerError });
+ },
+ deps,
+ );
+ } catch (err) {
+ // The mount helper's failures (attach refused, no .app inside) are
+ // infrastructure by construction β€” the DMG never got far enough to say
+ // anything about the app.
+ return {
+ verdict: VERDICT.error,
+ reason: `could not prepare the DMG for smoking: ${err?.message ?? String(err)}`,
+ };
+ }
+}
+
+export async function runDriver(argv, deps = {}) {
+ const errStream = deps.errStream ?? ((s) => process.stderr.write(s));
+ const log = deps.log ?? ((s) => process.stdout.write(`${s}\n`));
+
+ const dmgPath = argv.slice(2).find((a) => !a.startsWith('-'));
+ if (!dmgPath) {
+ errStream('usage: smoke-packaged-dmg.mjs <path-to.dmg>\n');
+ return EXIT_CODES[VERDICT.error];
+ }
+
+ const result = await smokePackagedDmg(dmgPath, deps);
+ log(annotationFor(result.verdict, result.reason, dmgPath));
+ publishVerdict(result, deps);
+ // Fails closed: a workflow step that forgets to branch on the verdict still
+ // stops the job on fail or error.
+ return EXIT_CODES[result.verdict];
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+ runDriver(process.argv).then((code) => process.exit(code));
+}
diff --git a/.github/scripts/smoke-packaged-dmg.test.mjs b/.github/scripts/smoke-packaged-dmg.test.mjs
new file mode 100644
index 000000000..21a97363e
--- /dev/null
+++ b/.github/scripts/smoke-packaged-dmg.test.mjs
@@ -0,0 +1,268 @@
+import { describe, expect, test } from 'vitest';
+import { DmgMountError, MOUNT_ERROR_CODES } from './dmg-mount.mjs';
+import {
+ annotationFor,
+ classifyRun,
+ EXIT_CODES,
+ publishVerdict,
+ runDriver,
+ smokePackagedDmg,
+ VERDICT,
+} from './smoke-packaged-dmg.mjs';
+
+const report = (stats) => ({ stats });
+
+/** A mount stub that hands the callback a fixed app path. */
+const mountOk = async (_dmg, cb) => cb('/tmp/copy/OpenKnowledge.app');
+const mountThrows = (err) => async () => {
+ throw err;
+};
+
+function deps({ mount = mountOk, run, read }) {
+ return {
+ withMountedDmg: mount,
+ runPlaywright: run ?? (async () => ({ exitCode: 0 })),
+ readReport: read ?? (async () => report({ expected: 16, unexpected: 0, flaky: 0, skipped: 0 })),
+ };
+}
+
+describe('classifyRun', () => {
+ test('all executed tests passing is a pass', () => {
+ const v = classifyRun({
+ runExitCode: 0,
+ report: report({ expected: 16, unexpected: 0, flaky: 0, skipped: 2 }),
+ });
+ expect(v.verdict).toBe(VERDICT.pass);
+ expect(v.reason).toContain('16');
+ });
+
+ test('a genuine test failure is a fail, not an error', () => {
+ const v = classifyRun({
+ runExitCode: 1,
+ report: report({ expected: 14, unexpected: 2, flaky: 0, skipped: 0 }),
+ });
+ expect(v.verdict).toBe(VERDICT.fail);
+ expect(v.reason).toContain('2 of 16');
+ });
+
+ test('flaky-but-eventually-green counts as executed and passes', () => {
+ const v = classifyRun({
+ runExitCode: 0,
+ report: report({ expected: 15, unexpected: 0, flaky: 1, skipped: 0 }),
+ });
+ expect(v.verdict).toBe(VERDICT.pass);
+ });
+
+ test('zero executed tests is an error, never a pass', () => {
+ // The adversarial case: a DMG so broken Electron never launches makes every
+ // test skip, and a naive "no failures" reading would call that green.
+ const v = classifyRun({
+ runExitCode: 0,
+ report: report({ expected: 0, unexpected: 0, flaky: 0, skipped: 16 }),
+ });
+ expect(v.verdict).toBe(VERDICT.error);
+ expect(v.verdict).not.toBe(VERDICT.pass);
+ expect(v.reason).toContain('16 skipped');
+ });
+
+ test('a missing or unparseable report is an error', () => {
+ expect(classifyRun({ runExitCode: 0, report: null }).verdict).toBe(VERDICT.error);
+ expect(classifyRun({ runExitCode: 1, report: undefined }).verdict).toBe(VERDICT.error);
+ });
+
+ test('a runner that would not start is an error, not a fail', () => {
+ const v = classifyRun({ runExitCode: 1, report: null, runnerError: 'spawn pnpm ENOENT' });
+ expect(v.verdict).toBe(VERDICT.error);
+ expect(v.reason).toContain('ENOENT');
+ });
+
+ test('a non-zero exit with no failing test is an error, not a fail', () => {
+ const v = classifyRun({
+ runExitCode: 3,
+ report: report({ expected: 16, unexpected: 0, flaky: 0, skipped: 0 }),
+ });
+ expect(v.verdict).toBe(VERDICT.error);
+ expect(v.reason).toContain('exited 3');
+ });
+});
+
+describe('annotationFor', () => {
+ test('pass is a notice; fail and error are warnings and read differently', () => {
+ const pass = annotationFor(VERDICT.pass, 'r', '/a.dmg');
+ const fail = annotationFor(VERDICT.fail, 'r', '/a.dmg');
+ const error = annotationFor(VERDICT.error, 'r', '/a.dmg');
+ expect(pass.startsWith('::notice::')).toBe(true);
+ expect(fail.startsWith('::warning::')).toBe(true);
+ expect(error.startsWith('::warning::')).toBe(true);
+ expect(fail).not.toBe(error);
+ expect(fail).toContain('FAILED');
+ expect(error).toContain('ERRORED');
+ expect(error).toContain('infrastructure');
+ expect(fail).not.toContain('ERRORED');
+ });
+});
+
+describe('publishVerdict', () => {
+ test('writes verdict and reason to the step-output file when present', () => {
+ const writes = [];
+ publishVerdict(
+ { verdict: VERDICT.fail, reason: 'two tests failed' },
+ {
+ env: { GITHUB_OUTPUT: '/tmp/out.txt' },
+ appendFileSync: (p, s) => writes.push([p, s]),
+ },
+ );
+ expect(writes).toEqual([['/tmp/out.txt', 'verdict=fail\nreason=two tests failed\n']]);
+ });
+
+ test('flattens newlines so the key=value format cannot be corrupted', () => {
+ const writes = [];
+ publishVerdict(
+ { verdict: VERDICT.error, reason: 'line one\nline two' },
+ { env: { GITHUB_OUTPUT: '/tmp/out.txt' }, appendFileSync: (_p, s) => writes.push(s) },
+ );
+ expect(writes[0]).toBe('verdict=error\nreason=line one line two\n');
+ });
+
+ test('echoes to stdout when there is no step-output file', () => {
+ const out = [];
+ publishVerdict(
+ { verdict: VERDICT.pass, reason: 'ok' },
+ { env: {}, writeStream: (s) => out.push(s) },
+ );
+ expect(out.join('')).toBe('verdict=pass\nreason=ok\n');
+ });
+});
+
+describe('smokePackagedDmg', () => {
+ test('passes the copied app path to the runner', async () => {
+ let seen = null;
+ const v = await smokePackagedDmg(
+ '/tmp/OpenKnowledge.dmg',
+ deps({
+ run: async (appPath) => {
+ seen = appPath;
+ return { exitCode: 0 };
+ },
+ }),
+ );
+ expect(seen).toBe('/tmp/copy/OpenKnowledge.app');
+ expect(v.verdict).toBe(VERDICT.pass);
+ });
+
+ test('a mount failure becomes an error verdict rather than throwing', async () => {
+ const v = await smokePackagedDmg(
+ '/tmp/broken.dmg',
+ deps({
+ mount: mountThrows(
+ new DmgMountError(
+ 'hdiutil attach failed: no mountable file systems',
+ MOUNT_ERROR_CODES.attachFailed,
+ ),
+ ),
+ }),
+ );
+ expect(v.verdict).toBe(VERDICT.error);
+ expect(v.reason).toContain('no mountable file systems');
+ });
+
+ test('a DMG with no .app inside becomes an error verdict', async () => {
+ const v = await smokePackagedDmg(
+ '/tmp/empty.dmg',
+ deps({
+ mount: mountThrows(
+ new DmgMountError('No .app bundle found in mounted DMG', MOUNT_ERROR_CODES.noAppBundle),
+ ),
+ }),
+ );
+ expect(v.verdict).toBe(VERDICT.error);
+ expect(v.reason).toContain('No .app bundle');
+ });
+
+ test('a wholly-skipped run against a broken DMG is an error', async () => {
+ const v = await smokePackagedDmg(
+ '/tmp/broken.dmg',
+ deps({
+ run: async () => ({ exitCode: 0 }),
+ read: async () => report({ expected: 0, unexpected: 0, flaky: 0, skipped: 16 }),
+ }),
+ );
+ expect(v.verdict).toBe(VERDICT.error);
+ });
+
+ test('a missing report is an error', async () => {
+ const v = await smokePackagedDmg('/tmp/OpenKnowledge.dmg', deps({ read: async () => null }));
+ expect(v.verdict).toBe(VERDICT.error);
+ });
+});
+
+describe('runDriver', () => {
+ function driverDeps(over) {
+ const lines = [];
+ const outputs = [];
+ return {
+ lines,
+ outputs,
+ deps: {
+ ...deps(over ?? {}),
+ log: (s) => lines.push(s),
+ errStream: (s) => lines.push(s),
+ env: { GITHUB_OUTPUT: '/tmp/out.txt' },
+ appendFileSync: (_p, s) => outputs.push(s),
+ },
+ };
+ }
+
+ test('exits 0 and annotates on pass', async () => {
+ const { lines, outputs, deps: d } = driverDeps();
+ const code = await runDriver(['node', 'x', '/tmp/OpenKnowledge.dmg'], d);
+ expect(code).toBe(0);
+ expect(lines[0]).toContain('::notice::');
+ expect(outputs[0]).toContain('verdict=pass');
+ });
+
+ test('exits non-zero on fail so a step that forgets to branch still fails closed', async () => {
+ const { outputs, deps: d } = driverDeps({
+ run: async () => ({ exitCode: 1 }),
+ read: async () => report({ expected: 14, unexpected: 2, flaky: 0, skipped: 0 }),
+ });
+ const code = await runDriver(['node', 'x', '/tmp/OpenKnowledge.dmg'], d);
+ expect(code).not.toBe(0);
+ expect(code).toBe(EXIT_CODES[VERDICT.fail]);
+ expect(outputs[0]).toContain('verdict=fail');
+ });
+
+ test('exits non-zero on error, with a code distinct from fail', async () => {
+ const { deps: d } = driverDeps({ read: async () => null });
+ const code = await runDriver(['node', 'x', '/tmp/OpenKnowledge.dmg'], d);
+ expect(code).toBe(EXIT_CODES[VERDICT.error]);
+ expect(EXIT_CODES[VERDICT.error]).not.toBe(EXIT_CODES[VERDICT.fail]);
+ });
+
+ test('a missing argument is an error, not a silent pass', async () => {
+ const { deps: d } = driverDeps();
+ expect(await runDriver(['node', 'x'], d)).toBe(EXIT_CODES[VERDICT.error]);
+ });
+});
+
+describe('defensive defaults are pinned, not incidental', () => {
+ // These `?? 0` fallbacks read as dead code to anyone tidying up. They are
+ // the difference between "Playwright renamed a field" surfacing as an error
+ // verdict and surfacing as a silent pass.
+ test('a report with no stats key is an error, not a pass', () => {
+ expect(classifyRun({ runExitCode: 0, report: {} }).verdict).toBe(VERDICT.error);
+ });
+
+ test('a report with an empty stats object is an error, not a pass', () => {
+ expect(classifyRun({ runExitCode: 0, report: { stats: {} } }).verdict).toBe(VERDICT.error);
+ });
+
+ test('a partial stats object still counts what is there', () => {
+ expect(classifyRun({ runExitCode: 0, report: { stats: { expected: 3 } } }).verdict).toBe(
+ VERDICT.pass,
+ );
+ expect(classifyRun({ runExitCode: 1, report: { stats: { unexpected: 1 } } }).verdict).toBe(
+ VERDICT.fail,
+ );
+ });
+});
diff --git a/.github/workflows/desktop-release.yml b/.github/workflows/desktop-release.yml
index 5f215220d..881918363 100644
--- a/.github/workflows/desktop-release.yml
+++ b/.github/workflows/desktop-release.yml
@@ -463,6 +463,63 @@ jobs:
attempt=$((attempt + 1))
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.
+ #
+ # 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
+ # at the promoted beta's commit, which for the first releases after this
+ # lands will not contain the smoke harness. Blocking a release because
+ # the gate did not exist yet would be wrong; the gate applies from the
+ # first tag that carries it.
+ #
+ # Stable only. Every beta cut flows through this same job on
+ # channel=beta, and FR5b is scoped to the stable artifact β€” the beta
+ # equivalent is the selection-time gate in select-beta-to-promote.yml,
+ # which smokes an already-published beta without standing between a cut
+ # and its release. Smoking here on beta would add 5-15 min to every
+ # cadence cut and let a bad DMG block the cadence itself.
+ - name: Smoke the packaged DMG (FR5b)
+ id: dmg_smoke
+ if: steps.channel.outputs.channel == 'latest'
+ env:
+ RELEASE_TAG: ${{ github.event.client_payload.release_tag || inputs.release_tag }}
+ run: |
+ set -euo pipefail
+ CONFIG="packages/desktop/playwright.packaged.config.ts"
+ DRIVER=".github/scripts/smoke-packaged-dmg.mjs"
+ if [[ ! -f "$CONFIG" || ! -f "$DRIVER" ]]; then
+ echo "verdict=skipped" >> "$GITHUB_OUTPUT"
+ echo "reason=the smoke harness is not present at ${RELEASE_TAG}" >> "$GITHUB_OUTPUT"
+ echo "::notice::DMG smoke gate absent at ${RELEASE_TAG} (ref predates the harness) β€” releasing without it. Later tags carry the gate."
+ exit 0
+ fi
+ # `.dmg.blockmap` sorts next to `.dmg`; match only the bundle itself.
+ # `|| true` keeps `set -e` from killing the step when dist-desktop is
+ # absent β€” the explicit empty-DMG guard below owns that message.
+ DMG="$(find packages/desktop/dist-desktop -maxdepth 1 -name '*.dmg' 2>/dev/null | head -1 || true)"
+ if [[ -z "$DMG" ]]; then
+ echo "verdict=error" >> "$GITHUB_OUTPUT"
+ echo "reason=electron-builder produced no .dmg to smoke" >> "$GITHUB_OUTPUT"
+ echo "::error::No .dmg found under packages/desktop/dist-desktop for ${RELEASE_TAG}; refusing to publish an unverified release."
+ exit 1
+ fi
+ echo "Smoking ${DMG} for ${RELEASE_TAG}…"
+ # The driver writes verdict= / reason= to GITHUB_OUTPUT itself and
+ # exits 0 / 1 / 2 for pass / fail / error, so this step fails closed
+ # on both non-pass verdicts without any branching here.
+ node "$DRIVER" "$DMG"
+
# 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
@@ -504,6 +561,61 @@ 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.
+ #
+ # 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
+ # a manual workflow_dispatch recovery re-run must never re-publish a
+ # version that is already on npm.
+ #
+ # `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.
+ - name: Trigger release.yml to publish stable to npm
+ if: success() && steps.channel.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 }}
+ run: |
+ set -euo pipefail
+ SELF_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 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."
+ # Best-effort forward-link to the release.yml run we just triggered.
+ CHILD=""
+ for _ in 1 2 3 4 5 6; do
+ CHILD=$(gh run list --workflow=release.yml --event=repository_dispatch --limit 8 --json url,createdAt \
+ --jq "[.[] | select(.createdAt >= \"$SINCE\")] | sort_by(.createdAt) | last | .url // empty" 2>/dev/null || true)
+ [[ -n "$CHILD" ]] && break
+ sleep 3
+ done
+ {
+ echo "### Dispatched release.yml (npm publish)"
+ echo "- Gated on the DMG smoke verdict: \`${{ steps.dmg_smoke.outputs.verdict }}\`"
+ if [[ -n "$CHILD" ]]; then echo "- Run: ${CHILD}"; else echo "- (run link unresolved; open release.yml)"; fi
+ } >> "$GITHUB_STEP_SUMMARY"
+
# The on-site changelog (/docs/changelog) is rebuilt by
# public-open-knowledge-docs-changelog-deploy.yml (on agents-private), which
# fires the Vercel deploy hook when the `main-reset` commit rewrites
@@ -651,6 +763,93 @@ jobs:
# 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
+ # "πŸŽ‰ OpenKnowledge X.Y.Z released" post that lands in the same channels.
+ #
+ # `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).
+ #
+ # No new secret: SLACK_WEBHOOK_URL / DISCORD_WEBHOOK_URL already exist
+ # and are consumed by the announcement steps above with the same
+ # unset -> ::notice:: -> skip tolerance.
+ - 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'
+ env:
+ SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+ DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_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 }}
+ 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.
+ VERDICT="${SMOKE_VERDICT:-}"
+ if [[ "$VERDICT" != "fail" ]]; then
+ VERDICT="error"
+ fi
+ REASON="${SMOKE_REASON:-the release job failed before the smoke gate reached a verdict}"
+ 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 channel="$1" webhook="$2" label="$3"
+ if [[ -z "$webhook" ]]; then
+ echo "::notice::${label} webhook not set β€” skipping the ${label} smoke alert for ${RELEASE_TAG}."
+ return 0
+ fi
+ local payload=""
+ if [[ -f "$BUILDER" ]]; then
+ payload="$(node "$BUILDER" --channel "$channel" --tag "$RELEASE_TAG" \
+ --verdict "$VERDICT" --reason "$REASON" --run-url "$RUN_URL" || true)"
+ fi
+ if [[ -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}" '{content: $t, 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.
+ if curl -sS --fail -X POST -H 'Content-type: application/json' --data "$payload" "$webhook"; then
+ echo "Posted the ${label} smoke alert for ${RELEASE_TAG}."
+ else
+ echo "::warning::${label} smoke alert failed to POST for ${RELEASE_TAG} β€” the release is still blocked; only the notification was lost."
+ fi
+ }
+
+ post slack "${SLACK_WEBHOOK_URL:-}" Slack
+ post discord "${DISCORD_WEBHOOK_URL:-}" Discord
+ # 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."
+
- name: Warn on stuck draft
if: failure()
env:
diff --git a/.github/workflows/promote-stable.yml b/.github/workflows/promote-stable.yml
index de64a9ff4..046337d97 100644
--- a/.github/workflows/promote-stable.yml
+++ b/.github/workflows/promote-stable.yml
@@ -17,14 +17,26 @@ name: Promote stable
# committed jq override, so the tag name is the only authoritative
# source of the cycle version.
# 3. Tags vX.Y.Z (no suffix) at the SAME SHA as the beta tag.
-# 4. Creates a non-prerelease GitHub Release at vX.Y.Z. desktop-release.yml
-# fires automatically and builds the stable DMG with
+# 4. Creates a non-prerelease GitHub Release at vX.Y.Z as a DRAFT.
+# desktop-release.yml fires automatically and builds the stable DMG with
# --config.extraMetadata.version=X.Y.Z (override since the legacy commit
# still has -beta.N in package.json).
-# 5. Promotes npm `latest` dist-tag using a transient package.json#version
+# 5. desktop-release.yml smokes that DMG, promotes the draft to published,
+# and only then dispatches publish-stable to release.yml, which promotes
+# the npm `latest` dist-tag using a transient package.json#version
# override (same primitive as D11/D13 of the spec β€” mutation lives only
# for the workflow run, not committed).
#
+# Cascade order changed in the DMG-smoke-gate work: this workflow used to
+# dispatch publish-stable itself, immediately after creating the draft
+# Release and BEFORE desktop-release.yml had built anything. npm `latest`
+# could therefore move for a release whose DMG later failed to build at all.
+# The dispatch now lives in desktop-release.yml, downstream of the DMG smoke
+# verdict, so a broken stable artifact can never reach npm. A macOS build is
+# deliberately NOT added here: this workflow holds the shared
+# `ok-release-cadence` lock at WORKFLOW level, so a 15-75 min build here
+# would block every beta cut for the duration.
+#
# After a successful cut this dispatches main-reset.yml on
# inkeep/agents-private (via the "Inkeep OK Release Bridge" App) to advance
# the base for the next cycle β€” one-button promotion. When the bridge App
@@ -410,55 +422,6 @@ jobs:
--notes-file "$BODY_FILE"
fi
- - name: Trigger release.yml to publish stable to npm
- if: steps.ver.outputs.skip != 'true'
- # Same-repo repository_dispatch into release.yml. release.yml
- # listens for event_type=publish-stable, checks out the stable
- # tag, applies the transient package.json#version override, and
- # runs `pnpm exec changeset publish --tag latest --provenance` via
- # npm Trusted Publishing OIDC.
- #
- # Why we delegate to release.yml instead of publishing here:
- # npm Trusted Publishing only allows ONE trusted-publisher entry
- # per package. Centralizing the publish call in release.yml
- # means the npmjs.com TP entry only authorizes one workflow
- # filename. promote-stable.yml owns tag + Release creation; npm
- # publishing lives in release.yml.
- #
- # Dispatch runs under the App-minted token so the sender identity
- # is consistent with the rest of this workflow. The dispatched
- # release.yml run gets its own OIDC identity (workflow=release.yml)
- # which is what the npm TP entry binds against β€” the sender is
- # not part of the TP claim, so swapping it from GITHUB_TOKEN to
- # the App token does not affect publish auth.
- env:
- GH_TOKEN: ${{ steps.app-token.outputs.token }}
- STABLE_TAG: ${{ steps.ver.outputs.stable_tag }}
- STABLE_VERSION: ${{ steps.ver.outputs.stable_version }}
- run: |
- set -euo pipefail
- SELF_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 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})."
- # Best-effort forward-link to the release.yml run we just triggered.
- CHILD=""
- for _ in 1 2 3 4 5 6; do
- CHILD=$(gh run list --workflow=release.yml --event=repository_dispatch --limit 8 --json url,createdAt \
- --jq "[.[] | select(.createdAt >= \"$SINCE\")] | sort_by(.createdAt) | last | .url // empty" 2>/dev/null || true)
- [[ -n "$CHILD" ]] && break
- sleep 3
- done
- {
- echo "### Dispatched release.yml (npm publish)"
- if [[ -n "$CHILD" ]]; then echo "- Run: ${CHILD}"; else echo "- (run link unresolved; open release.yml)"; fi
- } >> "$GITHUB_STEP_SUMMARY"
-
- name: Trigger desktop-release.yml to build + upload stable DMG
if: steps.ver.outputs.skip != 'true'
# The `gh release create` above creates the release as `--draft`
@@ -472,6 +435,11 @@ jobs:
# cascade workflow events; the token swap in this PR does not
# remove the need for the explicit dispatch β€” the draft state
# is the load-bearing reason.)
+ #
+ # This is now the ONLY cascade dispatch this workflow makes for the
+ # release itself: desktop-release.yml smokes the DMG it builds, and
+ # only then dispatches publish-stable to release.yml. This workflow
+ # deliberately no longer touches npm.
env:
GH_TOKEN: ${{ steps.app-token.outputs.token }}
STABLE_TAG: ${{ steps.ver.outputs.stable_tag }}
@@ -497,6 +465,7 @@ jobs:
{
echo "### Dispatched desktop-release.yml (signed DMG)"
if [[ -n "$CHILD" ]]; then echo "- Run: ${CHILD}"; else echo "- (run link unresolved; open desktop-release.yml)"; fi
+ echo "- That run smokes the DMG, promotes the draft Release, then dispatches publish-stable to release.yml for npm. npm \`latest\` does NOT move until the smoke passes."
} >> "$GITHUB_STEP_SUMMARY"
- name: Detect bridge App for cross-repo dispatch
diff --git a/.github/workflows/select-beta-to-promote.yml b/.github/workflows/select-beta-to-promote.yml
index a1d3d5c16..e7d2c52b3 100644
--- a/.github/workflows/select-beta-to-promote.yml
+++ b/.github/workflows/select-beta-to-promote.yml
@@ -58,6 +58,13 @@ name: Select beta to promote
# check skips when a promote-stable run is already in_progress/queued, and
# (3) the script stops at the first already-shipped beta (commit contained in the
# latest stable) and never selects one whose changes are already released.
+#
+# FAST TIER (FR5a), BUILT BUT UNARMED: a second job smokes an under-soaked
+# beta's DMG and, only on a clean smoke, dispatches promote-stable early. It is
+# gated on `fast_tier_candidate`, which the selection script writes empty today,
+# so it never runs and adds zero per-tick cost. A fail or an error verdict only
+# ever declines the early promotion β€” the 24h path is untouched and the gate can
+# never block a release. Arming steps are documented in RELEASES.md.
on:
schedule:
@@ -106,6 +113,14 @@ jobs:
name: Evaluate 24h soak + business-hours gate
runs-on: ubuntu-latest
timeout-minutes: 10
+ outputs:
+ # Seam for the FR5a fast tier. The selection script writes this EMPTY
+ # today β€” `main()` supplies no fast-tier predicate, so nothing ever
+ # qualifies and the macOS smoke leg below never runs. Per-tick cost of the
+ # fast tier is therefore exactly zero. Arming it is a documented operator
+ # step in RELEASES.md, not a side effect of merging.
+ fast_tier_candidate: ${{ steps.select.outputs.fast_tier_candidate }}
+ tier: ${{ steps.select.outputs.tier }}
steps:
- name: Business-hours gate (America/New_York)
id: hours
@@ -211,3 +226,167 @@ jobs:
if [[ -n "$CHILD" ]]; then echo "- Run: ${CHILD}"; else echo "- (run link unresolved; open the promote-stable workflow)"; fi
} >> "$GITHUB_STEP_SUMMARY"
if [[ -n "$CHILD" ]]; then echo "::notice::promote-stable run: ${CHILD}"; fi
+
+ # FR5a β€” selection-time DMG smoke for the fast tier.
+ #
+ # INERT BY DEFAULT. `fast_tier_candidate` is always empty (see the evaluate
+ # job's outputs), so this job is skipped on every tick and the fast tier costs
+ # nothing. It exists so arming is a configuration change rather than a code
+ # change.
+ #
+ # This job NEVER blocks a release. It cannot fail the 24h path: the evaluate
+ # job has already dispatched (or not) by the time this runs, on its own
+ # decision, and this job only ever ADDS an early promotion. A fail or an error
+ # verdict simply means no fast-tier dispatch happens and the beta waits out
+ # its normal 24h soak on a later tick.
+ #
+ # Interrupt-safe by construction. The workflow's concurrency group is
+ # `cancel-in-progress: true`, so a tick can be superseded mid-run at any
+ # point. This job holds no state a killed run could corrupt: it downloads to
+ # the runner's scratch, mounts through the helper (which detaches on SIGTERM),
+ # and its only effect is the final dispatch. Re-running reaches the same
+ # decision from the same inputs.
+ smoke-fast-tier-candidate:
+ name: Smoke the fast-tier candidate's DMG
+ needs: evaluate
+ if: needs.evaluate.outputs.fast_tier_candidate != ''
+ # Apple Silicon: the DMG is a Universal build, but launching it needs macOS.
+ runs-on: macos-26
+ timeout-minutes: 30
+ steps:
+ - name: Checkout
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ persist-credentials: false
+
+ - name: Set up Node
+ uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+ with:
+ node-version: "24"
+
+ - name: Install dependencies
+ run: |
+ set -euo pipefail
+ corepack enable
+ pnpm install --frozen-lockfile
+
+ - name: Download the candidate's DMG
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ CANDIDATE: ${{ needs.evaluate.outputs.fast_tier_candidate }}
+ run: |
+ set -euo pipefail
+ mkdir -p "${RUNNER_TEMP}/fast-tier-dmg"
+ gh release download "$CANDIDATE" --pattern '*.dmg' --dir "${RUNNER_TEMP}/fast-tier-dmg"
+
+ - name: Smoke the DMG
+ id: smoke
+ env:
+ CANDIDATE: ${{ needs.evaluate.outputs.fast_tier_candidate }}
+ run: |
+ set -uo pipefail
+ DMG="$(find "${RUNNER_TEMP}/fast-tier-dmg" -maxdepth 1 -name '*.dmg' | head -1)"
+ if [[ -z "$DMG" ]]; then
+ echo "verdict=error" >> "$GITHUB_OUTPUT"
+ echo "::warning::No .dmg downloaded for ${CANDIDATE}; refusing the fast tier (the 24h path is unaffected)."
+ exit 0
+ fi
+ # The driver exits non-zero on fail and error. `|| true` is correct
+ # here and only here: this job must never fail, and the verdict it
+ # wrote to GITHUB_OUTPUT is the signal the dispatch below reads.
+ node .github/scripts/smoke-packaged-dmg.mjs "$DMG" || true
+
+ - name: Dispatch promote-stable for the smoke-proven candidate
+ if: steps.smoke.outputs.verdict == 'pass'
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ CANDIDATE: ${{ needs.evaluate.outputs.fast_tier_candidate }}
+ run: |
+ set -euo pipefail
+ # Same in-flight guard the 24h path uses β€” don't double-fire while a
+ # promotion is already running.
+ active=$(gh run list --workflow=promote-stable.yml --json status \
+ --jq '[.[] | select(.status=="in_progress" or .status=="queued")] | length')
+ if [[ "$active" -gt 0 ]]; then
+ echo "::notice::A promote-stable run is already in_progress/queued (${active}); skipping the fast-tier dispatch."
+ exit 0
+ fi
+ SELF_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
+ gh workflow run promote-stable.yml -f beta_tag="$CANDIDATE" -f dispatched_by="$SELF_URL"
+ echo "::notice::Fast tier: dispatched promote-stable for ${CANDIDATE} after its DMG smoked clean."
+
+ - name: Record a fast-tier refusal
+ if: steps.smoke.outputs.verdict != 'pass'
+ env:
+ CANDIDATE: ${{ needs.evaluate.outputs.fast_tier_candidate }}
+ VERDICT: ${{ steps.smoke.outputs.verdict }}
+ run: |
+ echo "::notice::Fast tier refused for ${CANDIDATE} (verdict=${VERDICT:-unknown}). The 24h tier is unaffected; this beta promotes normally once it has soaked."
+
+ # Aggregate silent-failure alarm.
+ #
+ # The per-cut alert in desktop-release.yml covers a gate that BITES. This
+ # covers the failure mode nobody notices: a gate that is quietly
+ # always-refusing, or a fast tier that has gone inert. Both look exactly like
+ # a calm week.
+ #
+ # Silent by default and by design. With the fast tier unarmed the smoke job
+ # never runs, the derived history is empty, and the evaluator reports no
+ # alarm β€” an intentionally disarmed tier is not a broken one, and an alarm
+ # that fired continuously while the tier was off would train responders to
+ # ignore it.
+ #
+ # Schedule-only: the alarm is about a trend, so evaluating it on every push
+ # would add noise without adding signal. Stateless β€” it derives history from
+ # this workflow's own run records and writes nothing back.
+ aggregate-smoke-alarm:
+ name: Aggregate DMG-smoke alarm
+ if: github.event_name == 'schedule'
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ steps:
+ - name: Checkout
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ persist-credentials: false
+
+ - name: Set up Node
+ uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+ with:
+ node-version: "24"
+
+ - name: Evaluate the aggregate alarm
+ id: alarm
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: node .github/scripts/evaluate-smoke-alarm.mjs
+
+ # Routed to the same channels as the per-cut smoke alert, not to a
+ # workflow annotation alone β€” an annotation on a scheduled job nobody
+ # opens is indistinguishable from silence.
+ - name: Page the release channel
+ if: steps.alarm.outputs.alarm == 'true'
+ env:
+ SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+ DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
+ REASONS: ${{ steps.alarm.outputs.reasons }}
+ run: |
+ set -uo pipefail
+ RUN_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
+ TEXT="🚨 DMG SMOKE GATE ALARM β€” ${REASONS}. Investigate before trusting the fast tier. ${RUN_URL}"
+ payload="$(jq -nc --arg t "$TEXT" '{content: $t, text: $t}')"
+ post() {
+ local webhook="$1" label="$2"
+ if [[ -z "$webhook" ]]; then
+ echo "::notice::${label} webhook not set β€” skipping the ${label} aggregate alarm."
+ return 0
+ fi
+ if curl -sS --fail -X POST -H 'Content-type: application/json' --data "$payload" "$webhook"; then
+ echo "Posted the ${label} aggregate alarm."
+ else
+ echo "::warning::${label} aggregate alarm failed to POST β€” the alarm condition still holds."
+ fi
+ }
+ post "${SLACK_WEBHOOK_URL:-}" Slack
+ post "${DISCORD_WEBHOOK_URL:-}" Discord
+ echo "::warning::DMG smoke gate alarm: ${REASONS}"
diff --git a/packages/desktop/playwright.packaged.config.ts b/packages/desktop/playwright.packaged.config.ts
new file mode 100644
index 000000000..f046af819
--- /dev/null
+++ b/packages/desktop/playwright.packaged.config.ts
@@ -0,0 +1,54 @@
+import { defineConfig } from '@playwright/test';
+
+/**
+ * Packaged-app Playwright config β€” the release-gate tier.
+ *
+ * Runs a deliberately small subset of the SAME smoke files as
+ * `playwright.config.ts`, but against a packaged `.app` bundle selected via
+ * `OK_DESKTOP_PACKAGED_APP` (see `tests/smoke/_helpers/launch-desktop.ts`).
+ * Two configs, one set of test files.
+ *
+ * Why a separate file rather than a `projects` array on the existing config:
+ * introducing projects changes `testInfo.project.retries` resolution, which
+ * `tests/smoke/_helpers/electron-stderr.ts` reads to decide whether to attach
+ * main-process stderr. The required `desktop-smoke` check must keep behaving
+ * exactly as it does today, so it keeps its own config untouched.
+ *
+ * No `globalSetup`: the unpackaged config's stale-build guard compares `src/`
+ * against `out/`, neither of which describes a packaged bundle β€” running it
+ * here would fail on a perfectly good DMG.
+ */
+
+/**
+ * The FR5a subset: launch, project creation, and first-launch MCP wiring. This
+ * is the smallest set that proves a DMG boots, reaches the renderer, and can
+ * complete the first-run flow. Widening or narrowing it is a deliberate act β€”
+ * `tests/unit/playwright-packaged-config.test.ts` pins the list.
+ */
+export const PACKAGED_SMOKE_SUBSET = [
+ 'consent-dialog.e2e.ts',
+ 'create-new-project.e2e.ts',
+ 'mcp-wiring.e2e.ts',
+] as const;
+
+/** Distinct from the unpackaged report so the two never overwrite each other. */
+export const PACKAGED_JSON_REPORT_PATH = 'test-results/desktop-smoke-packaged-results.json';
+
+export default defineConfig({
+ testDir: './tests/smoke',
+ testMatch: PACKAGED_SMOKE_SUBSET.map((file) => `**/${file}`),
+ // Matches the unpackaged config's CI budget. A packaged launch is if anything
+ // slower than `electron out/main/index.js` (Gatekeeper assessment, first-run
+ // dyld cache warm-up), so a tighter budget would only add flake.
+ timeout: process.env.CI ? 150_000 : 60_000,
+ retries: process.env.CI ? 2 : 0,
+ failOnFlakyTests: false,
+ workers: 1,
+ fullyParallel: false,
+ // `json` is what the driver parses for its verdict; `list` keeps the CI log
+ // readable. No `html` β€” nothing uploads a report for this tier.
+ reporter: [['list'], ['json', { outputFile: PACKAGED_JSON_REPORT_PATH }]],
+ use: {
+ trace: 'retain-on-failure',
+ },
+});
diff --git a/packages/desktop/tests/smoke/_helpers/launch-desktop.test.ts b/packages/desktop/tests/smoke/_helpers/launch-desktop.test.ts
new file mode 100644
index 000000000..76fe833d3
--- /dev/null
+++ b/packages/desktop/tests/smoke/_helpers/launch-desktop.test.ts
@@ -0,0 +1,138 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import {
+ DEFAULT_LAUNCH_TIMEOUT_MS,
+ DEFAULT_LOCAL_PACKAGED_APP,
+ desktopLaunchOptions,
+ executableForAppBundle,
+ PACKAGED_APP_ENV,
+ resolveDesktopTarget,
+ UNPACKAGED_MAIN_ENTRY,
+} from './launch-desktop';
+
+const unpackaged = {
+ mode: 'unpackaged' as const,
+ targetPath: '/repo/out/main/index.js',
+ exists: true,
+ missingReason: 'x',
+};
+const packaged = {
+ mode: 'packaged' as const,
+ appPath: '/mnt/OpenKnowledge.app',
+ targetPath: '/mnt/OpenKnowledge.app/Contents/MacOS/OpenKnowledge',
+ exists: true,
+ missingReason: 'x',
+};
+
+describe('resolveDesktopTarget', () => {
+ it('resolves the unpackaged main entry when no packaged override is set', () => {
+ const target = resolveDesktopTarget({ env: {} });
+ expect(target.mode).toBe('unpackaged');
+ expect(target.targetPath).toBe(UNPACKAGED_MAIN_ENTRY);
+ expect(target.appPath).toBeUndefined();
+ });
+
+ it('treats an empty override as absent', () => {
+ expect(resolveDesktopTarget({ env: { [PACKAGED_APP_ENV]: '' } }).mode).toBe('unpackaged');
+ });
+
+ it('resolves the bundle executable when the override names an .app', () => {
+ const target = resolveDesktopTarget({ env: { [PACKAGED_APP_ENV]: '/mnt/OpenKnowledge.app' } });
+ expect(target.mode).toBe('packaged');
+ expect(target.appPath).toBe('/mnt/OpenKnowledge.app');
+ expect(target.targetPath).toBe('/mnt/OpenKnowledge.app/Contents/MacOS/OpenKnowledge');
+ });
+
+ it('falls back to the local packaged build for packaged-only suites', () => {
+ const target = resolveDesktopTarget({ env: {}, requirePackaged: true });
+ expect(target.mode).toBe('packaged');
+ expect(target.appPath).toBe(DEFAULT_LOCAL_PACKAGED_APP);
+ });
+
+ it('lets the override win over the packaged-only fallback', () => {
+ const target = resolveDesktopTarget({
+ env: { [PACKAGED_APP_ENV]: '/mnt/OpenKnowledge.app' },
+ requirePackaged: true,
+ });
+ expect(target.appPath).toBe('/mnt/OpenKnowledge.app');
+ });
+
+ it('reports existence and a mode-appropriate skip reason', () => {
+ const missing = resolveDesktopTarget({ env: { [PACKAGED_APP_ENV]: '/nope/Absent.app' } });
+ expect(missing.exists).toBe(false);
+ expect(missing.missingReason).toContain('/nope/Absent.app/Contents/MacOS/Absent');
+ // The suite migrated off Bun; the skip hint must not send a reader to it.
+ expect(resolveDesktopTarget({ env: {} }).missingReason).toContain('pnpm run build:desktop');
+ expect(resolveDesktopTarget({ env: {} }).missingReason).not.toContain('bun run');
+ });
+});
+
+describe('executableForAppBundle', () => {
+ it('derives Contents/MacOS/<name> from the bundle name', () => {
+ expect(executableForAppBundle('/Applications/OpenKnowledge.app')).toBe(
+ '/Applications/OpenKnowledge.app/Contents/MacOS/OpenKnowledge',
+ );
+ });
+});
+
+describe('desktopLaunchOptions', () => {
+ it('unpackaged: main entry leads args and no executablePath is set', () => {
+ const opts = desktopLaunchOptions({ target: unpackaged, args: ['--user-data-dir=/tmp/u'] });
+ expect(opts.args).toEqual(['/repo/out/main/index.js', '--user-data-dir=/tmp/u']);
+ expect('executablePath' in opts).toBe(false);
+ });
+
+ it('packaged: executablePath is set and the main entry is omitted from args', () => {
+ const opts = desktopLaunchOptions({ target: packaged, args: ['--user-data-dir=/tmp/u'] });
+ expect(opts.executablePath).toBe('/mnt/OpenKnowledge.app/Contents/MacOS/OpenKnowledge');
+ expect(opts.args).toEqual(['--user-data-dir=/tmp/u']);
+ expect(opts.args).not.toContain(UNPACKAGED_MAIN_ENTRY);
+ expect(opts.args.some((a) => a.endsWith('out/main/index.js'))).toBe(false);
+ });
+
+ it('omits the env key entirely when the caller supplies none', () => {
+ // Load-bearing: 8 smoke launch sites pass no env. A default env would give
+ // them OK_DESKTOP_E2E_SMOKE, which dialog-helpers and the instance-name
+ // resolver read unconditionally.
+ const opts = desktopLaunchOptions({ target: unpackaged });
+ expect('env' in opts).toBe(false);
+ });
+
+ it('passes a supplied env through unmodified', () => {
+ const env = { HOME: '/tmp/home', OK_DESKTOP_E2E_SMOKE: '1' };
+ const opts = desktopLaunchOptions({ target: unpackaged, env });
+ expect(opts.env).toEqual(env);
+ });
+
+ it('defaults the timeout to 30s and lets a caller override it', () => {
+ expect(desktopLaunchOptions({ target: unpackaged }).timeout).toBe(DEFAULT_LAUNCH_TIMEOUT_MS);
+ expect(DEFAULT_LAUNCH_TIMEOUT_MS).toBe(30_000);
+ expect(desktopLaunchOptions({ target: unpackaged, timeout: 90_000 }).timeout).toBe(90_000);
+ });
+
+ it('does not alias the caller args array', () => {
+ const args = ['--flag'];
+ const opts = desktopLaunchOptions({ target: packaged, args });
+ args.push('--mutated-after');
+ expect(opts.args).toEqual(['--flag']);
+ });
+});
+
+describe('no smoke file references __dirname without defining it', () => {
+ // Regression guard for the launch-helper migration. `__dirname` is not a
+ // runtime global under this package's "type": "module", but @types/node
+ // declares it ambiently β€” so a stale reference typechecks clean, and
+ // playwright.config.ts's testIgnore of `_*.e2e.ts` keeps CI from ever
+ // importing the dev-only files where it bit. The failure is a
+ // ReferenceError at module load, visible only to whoever runs the file
+ // directly. A static check is the only tier that catches it.
+ const SMOKE_DIR = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+ it.each(readdirSync(SMOKE_DIR).filter((f) => f.endsWith('.e2e.ts')))('%s', (file) => {
+ const src = readFileSync(join(SMOKE_DIR, file), 'utf8');
+ if (!src.includes('__dirname')) return;
+ expect(src, `${file} uses __dirname without defining it`).toMatch(/const __dirname\s*=/);
+ });
+});
diff --git a/packages/desktop/tests/smoke/_helpers/launch-desktop.ts b/packages/desktop/tests/smoke/_helpers/launch-desktop.ts
new file mode 100644
index 000000000..31ae744b3
--- /dev/null
+++ b/packages/desktop/tests/smoke/_helpers/launch-desktop.ts
@@ -0,0 +1,154 @@
+/**
+ * One launch convention for the Electron smoke suite.
+ *
+ * The suite runs in two structurally different shapes. Unpackaged it launches
+ * `electron` against `out/main/index.js`, passing that main entry as the first
+ * element of `args`. Packaged it launches the bundle's own binary via
+ * `executablePath` and must NOT pass a main entry at all β€” a path swap between
+ * the two does not work, which is why every call site routes through here.
+ *
+ * Mode is selected by `OK_DESKTOP_PACKAGED_APP`: set it to an `.app` bundle to
+ * run the same test files against a packaged build. Absent, the suite behaves
+ * exactly as it did before this helper existed.
+ *
+ * `env` is deliberately optional and never defaulted. Eight of the suite's
+ * launch sites pass no `env` today; handing them a default that included
+ * `OK_DESKTOP_E2E_SMOKE` would silently change behavior at
+ * `dialog-helpers.ts:readTestPickedPath` and `index.ts:resolveEffectiveInstanceName`,
+ * both of which read that variable unconditionally.
+ */
+
+import { existsSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { _electron as electron } from '@playwright/test';
+
+/** Playwright's own launch-options shape, so `env` stays exactly its type. */
+type ElectronLaunchOptions = NonNullable<Parameters<typeof electron.launch>[0]>;
+export type SmokeLaunchEnv = NonNullable<ElectronLaunchOptions['env']>;
+
+const HELPERS_DIR = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * `packages/desktop`. Exported so smoke files can resolve package-relative
+ * paths without each re-deriving `__dirname` β€” which is not a runtime global
+ * under this package's `"type": "module"`, and which `@types/node` declares
+ * ambiently so a stale reference typechecks clean and only fails at import.
+ */
+export const DESKTOP_ROOT = resolve(HELPERS_DIR, '..', '..', '..');
+
+/** Env var naming a packaged `.app` bundle to run the smoke subset against. */
+export const PACKAGED_APP_ENV = 'OK_DESKTOP_PACKAGED_APP';
+
+/** `electron-vite` output the unpackaged suite launches. */
+export const UNPACKAGED_MAIN_ENTRY = join(DESKTOP_ROOT, 'out', 'main', 'index.js');
+
+/**
+ * Where `electron-builder --mac` drops the unpacked bundle locally. Only used
+ * by suites that are packaged-only and get no env override β€” CI supplies the
+ * override, so this is the local-developer convenience path.
+ */
+export const DEFAULT_LOCAL_PACKAGED_APP = join(
+ DESKTOP_ROOT,
+ 'dist-desktop',
+ 'mac-arm64',
+ 'OpenKnowledge.app',
+);
+
+export type DesktopLaunchMode = 'packaged' | 'unpackaged';
+
+export interface DesktopTarget {
+ mode: DesktopLaunchMode;
+ /** `.app` bundle root in packaged mode; undefined otherwise. */
+ appPath?: string;
+ /** The main entry (unpackaged) or the bundle executable (packaged). */
+ targetPath: string;
+ exists: boolean;
+ /** Ready-to-use `test.skip` reason when `exists` is false. */
+ missingReason: string;
+}
+
+export interface ResolveDesktopTargetOptions {
+ env?: NodeJS.ProcessEnv;
+ /**
+ * Resolve a packaged target even without the env override, falling back to
+ * the local `electron-builder` output. For suites that only make sense
+ * against a packaged bundle.
+ */
+ requirePackaged?: boolean;
+}
+
+/** `<bundle>.app/Contents/MacOS/<bundle>` β€” electron-builder's layout. */
+export function executableForAppBundle(appPath: string): string {
+ return join(appPath, 'Contents', 'MacOS', basename(appPath, '.app'));
+}
+
+export function resolveDesktopTarget(options: ResolveDesktopTargetOptions = {}): DesktopTarget {
+ const env = options.env ?? process.env;
+ const override = env[PACKAGED_APP_ENV];
+ const appPath =
+ override && override.length > 0
+ ? resolve(override)
+ : options.requirePackaged
+ ? DEFAULT_LOCAL_PACKAGED_APP
+ : undefined;
+
+ if (appPath !== undefined) {
+ const targetPath = executableForAppBundle(appPath);
+ return {
+ mode: 'packaged',
+ appPath,
+ targetPath,
+ exists: existsSync(targetPath),
+ missingReason: `Packaged desktop build missing at ${targetPath} β€” build a packaged app, or point ${PACKAGED_APP_ENV} at one.`,
+ };
+ }
+
+ return {
+ mode: 'unpackaged',
+ targetPath: UNPACKAGED_MAIN_ENTRY,
+ exists: existsSync(UNPACKAGED_MAIN_ENTRY),
+ missingReason: `Main build missing at ${UNPACKAGED_MAIN_ENTRY} β€” run "pnpm run build:desktop" first.`,
+ };
+}
+
+export interface DesktopLaunchOptionsInput {
+ /** Defaults to `resolveDesktopTarget()`. */
+ target?: DesktopTarget;
+ /** Arguments after the main entry (`--user-data-dir=…`, deep links, flags). */
+ args?: string[];
+ /** Passed through verbatim. Omitted entirely when absent. */
+ env?: SmokeLaunchEnv;
+ /** Defaults to 30_000, matching every call site before this helper. */
+ timeout?: number;
+}
+
+export interface DesktopLaunchOptions {
+ args: string[];
+ timeout: number;
+ executablePath?: string;
+ env?: SmokeLaunchEnv;
+}
+
+export const DEFAULT_LAUNCH_TIMEOUT_MS = 30_000;
+
+/**
+ * Build the `electron.launch` options for the active mode. Unpackaged prepends
+ * the main entry to `args` and sets no `executablePath`; packaged sets
+ * `executablePath` and leaves `args` as the caller supplied them.
+ */
+export function desktopLaunchOptions(input: DesktopLaunchOptionsInput = {}): DesktopLaunchOptions {
+ const target = input.target ?? resolveDesktopTarget();
+ const extraArgs = input.args ?? [];
+ const timeout = input.timeout ?? DEFAULT_LAUNCH_TIMEOUT_MS;
+
+ const base: DesktopLaunchOptions =
+ target.mode === 'packaged'
+ ? { args: [...extraArgs], timeout, executablePath: target.targetPath }
+ : { args: [target.targetPath, ...extraArgs], timeout };
+
+ // Spread conditionally rather than assigning `env: input.env`: an explicit
+ // `env: undefined` key is not the same as no key to Playwright, and the
+ // no-env call sites depend on inheriting the parent environment untouched.
+ return input.env === undefined ? base : { ...base, env: input.env };
+}
diff --git a/packages/desktop/tests/smoke/_helpers/parse-timeouts.ts b/packages/desktop/tests/smoke/_helpers/parse-timeouts.ts
index c47c0bd27..47c679b80 100644
--- a/packages/desktop/tests/smoke/_helpers/parse-timeouts.ts
+++ b/packages/desktop/tests/smoke/_helpers/parse-timeouts.ts
@@ -28,8 +28,16 @@
*/
import { readFileSync } from 'node:fs';
+import { DEFAULT_LAUNCH_TIMEOUT_MS } from './launch-desktop';
const TIMEOUT_LITERAL_RE = /\btimeout:\s*(\d+(?:_\d+)*)/g;
+/**
+ * Smoke files launch through the shared helper rather than an inline
+ * `electron.launch({ timeout: 30_000 })`, so the parser has to know what that
+ * helper spends by default. Imported rather than duplicated so the two cannot
+ * drift.
+ */
+const LAUNCH_HELPER_CALL_RE = /\bdesktopLaunchOptions\(/;
const TOPASS_TIMEOUT_RE = /\.toPass\(\s*\{[^}]*timeout:\s*(\d+(?:_\d+)*)/g;
const DEFAULT_TIMEOUT_ARG_RE = /\btimeoutMs\s*=\s*(\d+(?:_\d+)*)/g;
const FUNCTION_HEADER_RE = /(?:^|\n)(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\(/g;
@@ -289,6 +297,14 @@ export function extractHelperBudgets(src: string): HelperBudget[] {
for (const tm of body.matchAll(TIMEOUT_LITERAL_RE)) {
budgets.push(parseNumericLiteral(tm[1]));
}
+ // `desktopLaunchOptions(...)` spends the shared launch default unless the
+ // call passes its own `timeout:` β€” which the literal scan above already
+ // counts, and `Math.max` below picks whichever is larger. Without this the
+ // budget would read 0 for every helper that launches Electron, silently
+ // understating the cumulative budget the calibration invariant checks.
+ if (LAUNCH_HELPER_CALL_RE.test(body)) {
+ budgets.push(DEFAULT_LAUNCH_TIMEOUT_MS);
+ }
const maxTimeoutMs = budgets.length > 0 ? Math.max(...budgets) : 0;
if (maxTimeoutMs > 0) {
helpers.push({ name, maxTimeoutMs });
diff --git a/packages/desktop/tests/smoke/_helpers/stale-build-guard.ts b/packages/desktop/tests/smoke/_helpers/stale-build-guard.ts
index fc92516c9..6e1d12221 100644
--- a/packages/desktop/tests/smoke/_helpers/stale-build-guard.ts
+++ b/packages/desktop/tests/smoke/_helpers/stale-build-guard.ts
@@ -14,7 +14,7 @@
* undefined; main rejected the IPC; consent dialog never rendered. Hours
* lost reading IPC choreography that was never actually broken.
*
- * In CI this can't happen β€” `bun run build:desktop` runs immediately
+ * In CI this can't happen β€” `pnpm run build:desktop` runs immediately
* before the test step. In local dev it happens whenever a contributor
* edits `src/` and starts a smoke run without rebuilding. This guard
* fires a clear diagnostic at globalSetup time so the wasted-debugging
@@ -94,7 +94,7 @@ export default function staleBuildGuard(): void {
'',
...stale,
'',
- 'Run `bun run build:desktop` from public/open-knowledge before re-running smoke tests.',
+ 'Run `pnpm run build:desktop` from public/open-knowledge before re-running smoke tests.',
'',
'Why this matters: the smoke harness launches `out/main/index.js` directly.',
'If `out/` is older than `src/`, tests run against a phantom version of the app',
diff --git a/packages/desktop/tests/smoke/_nav-empty-840x600.e2e.ts b/packages/desktop/tests/smoke/_nav-empty-840x600.e2e.ts
index 8d68813fa..611fece06 100644
--- a/packages/desktop/tests/smoke/_nav-empty-840x600.e2e.ts
+++ b/packages/desktop/tests/smoke/_nav-empty-840x600.e2e.ts
@@ -11,21 +11,23 @@
* Output: packages/desktop/tmp/nav-shot-empty-840x600.png
*/
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join, resolve } from 'node:path';
import type { ElectronApplication, JSHandle, Page } from '@playwright/test';
import { _electron as electron } from '@playwright/test';
+import {
+ DESKTOP_ROOT,
+ desktopLaunchOptions,
+ resolveDesktopTarget,
+} from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
-const SHOT_DIR = resolve(__dirname, '..', '..', 'tmp');
+const TARGET = resolveDesktopTarget();
+const SHOT_DIR = resolve(DESKTOP_ROOT, 'tmp');
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
function userDataDirFor(tmpHome: string): string {
return join(tmpHome, 'electron-userdata');
@@ -51,11 +53,14 @@ function seedEmptyHome(prefix: string): string {
}
async function launchApp(tmpHome: string): Promise<ElectronApplication> {
- return electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${userDataDirFor(tmpHome)}`],
- timeout: 30_000,
- env: { ...process.env, HOME: tmpHome, OK_DESKTOP_E2E_SMOKE: '1' },
- });
+ return electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${userDataDirFor(tmpHome)}`],
+ timeout: 30_000,
+ env: { ...process.env, HOME: tmpHome, OK_DESKTOP_E2E_SMOKE: '1' },
+ }),
+ );
}
async function findNavigator(app: ElectronApplication, timeoutMs = 20_000): Promise<Page> {
@@ -91,7 +96,7 @@ function rmSafe(p: string): void {
test.describe('Navigator empty-state screenshot (dev-only)', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run.');
test.skip(!DARWIN, 'Smoke harness is darwin-only in v0.');
- test.skip(!BUILD_EXISTS, `Main build missing at ${MAIN_ENTRY} β€” run "bun run build:desktop".`);
+ test.skip(!TARGET.exists, TARGET.missingReason);
test('capture empty Navigator at 840x600', async ({ captureStderrFor }) => {
test.setTimeout(90_000);
diff --git a/packages/desktop/tests/smoke/_nav-size-screenshots.e2e.ts b/packages/desktop/tests/smoke/_nav-size-screenshots.e2e.ts
index d9ee0121d..b4deaf4a4 100644
--- a/packages/desktop/tests/smoke/_nav-size-screenshots.e2e.ts
+++ b/packages/desktop/tests/smoke/_nav-size-screenshots.e2e.ts
@@ -11,21 +11,23 @@
* Output: packages/desktop/tmp/nav-shot-<w>x<h>.png (gitignored).
*/
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join, resolve } from 'node:path';
import type { ElectronApplication, JSHandle, Page } from '@playwright/test';
import { _electron as electron } from '@playwright/test';
+import {
+ DESKTOP_ROOT,
+ desktopLaunchOptions,
+ resolveDesktopTarget,
+} from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
-const SHOT_DIR = resolve(__dirname, '..', '..', 'tmp');
+const TARGET = resolveDesktopTarget();
+const SHOT_DIR = resolve(DESKTOP_ROOT, 'tmp');
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
const SIZES = [
{ w: 800, h: 750, label: 'current-800x750' },
@@ -83,11 +85,14 @@ function seedHome(prefix: string): { tmpHome: string; projectDir: string } {
}
async function launchApp(tmpHome: string): Promise<ElectronApplication> {
- return electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${userDataDirFor(tmpHome)}`],
- timeout: 30_000,
- env: { ...process.env, HOME: tmpHome, OK_DESKTOP_E2E_SMOKE: '1' },
- });
+ return electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${userDataDirFor(tmpHome)}`],
+ timeout: 30_000,
+ env: { ...process.env, HOME: tmpHome, OK_DESKTOP_E2E_SMOKE: '1' },
+ }),
+ );
}
async function findWindow(
@@ -127,7 +132,7 @@ function rmSafe(p: string): void {
test.describe('Navigator size screenshots (dev-only)', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run.');
test.skip(!DARWIN, 'Smoke harness is darwin-only in v0.');
- test.skip(!BUILD_EXISTS, `Main build missing at ${MAIN_ENTRY} β€” run "bun run build:desktop".`);
+ test.skip(!TARGET.exists, TARGET.missingReason);
test('capture Navigator at 3 candidate sizes', async ({ captureStderrFor }) => {
test.setTimeout(120_000);
diff --git a/packages/desktop/tests/smoke/agent-patch-divergence-probe.e2e.ts b/packages/desktop/tests/smoke/agent-patch-divergence-probe.e2e.ts
index 4a9f27f37..6c2269b16 100644
--- a/packages/desktop/tests/smoke/agent-patch-divergence-probe.e2e.ts
+++ b/packages/desktop/tests/smoke/agent-patch-divergence-probe.e2e.ts
@@ -36,16 +36,15 @@
*/
import { randomUUID } from 'node:crypto';
-import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { join } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
-import { fileURLToPath } from 'node:url';
import { type ElectronApplication, _electron as electron } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
@@ -293,7 +292,7 @@ async function setupElectron(
}> {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'Driver uses macOS open(1).');
- test.skip(!existsSync(MAIN_ENTRY), `out/main/index.js missing β€” run \`bun run build:desktop\`.`);
+ test.skip(!TARGET.exists, TARGET.missingReason);
const contentDir = mkdtempSync(join(tmpdir(), `ok-agent-patch-probe-${variantTag}-`));
const userDataDir = mkdtempSync(join(tmpdir(), `ok-pw-userdata-${variantTag}-`));
@@ -307,11 +306,14 @@ async function setupElectron(
const deepLink = `openknowledge://open?project=${encodeURIComponent(contentDir)}&doc=${encodeURIComponent(docName)}`;
- const app = await electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${userDataDir}`, deepLink],
- env: { ...process.env, NODE_ENV: 'production' },
- timeout: 30_000,
- });
+ const app = await electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${userDataDir}`, deepLink],
+ env: { ...process.env, NODE_ENV: 'production' },
+ timeout: 30_000,
+ }),
+ );
captureStderrFor(app);
// Find the editor window by hash.
diff --git a/packages/desktop/tests/smoke/consent-dialog.e2e.ts b/packages/desktop/tests/smoke/consent-dialog.e2e.ts
index f37d848c3..152b84518 100644
--- a/packages/desktop/tests/smoke/consent-dialog.e2e.ts
+++ b/packages/desktop/tests/smoke/consent-dialog.e2e.ts
@@ -32,19 +32,17 @@ import {
writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import type { ElectronApplication, Page } from '@playwright/test';
import { _electron as electron } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { clickNavOpen } from './_helpers/navigator-actions';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
const DESKTOP_PRODUCT_NAME = '@inkeep/open-knowledge-desktop';
@@ -105,16 +103,18 @@ async function launchApp(tmpHome: string, opts: LaunchOpts = {}): Promise<Electr
// Support state and `lastOpenedProject` from real usage causes the editor
// window to spawn instead of the navigator.
const userDataDir = join(tmpHome, 'Library', 'Application Support', DESKTOP_PRODUCT_NAME);
- return electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${userDataDir}`],
- timeout: 30_000,
- env: {
- ...process.env,
- HOME: tmpHome,
- OK_DESKTOP_E2E_SMOKE: '1',
- ...(opts.pickedPath !== undefined ? { OK_DESKTOP_TEST_PICKED_PATH: opts.pickedPath } : {}),
- },
- });
+ return electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${userDataDir}`],
+ env: {
+ ...process.env,
+ HOME: tmpHome,
+ OK_DESKTOP_E2E_SMOKE: '1',
+ ...(opts.pickedPath !== undefined ? { OK_DESKTOP_TEST_PICKED_PATH: opts.pickedPath } : {}),
+ },
+ }),
+ );
}
async function findWindowByMode(
@@ -175,10 +175,7 @@ function trackForCleanup(...paths: string[]): void {
test.describe('Consent-dialog smoke', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'Smoke harness is darwin-only.');
- test.skip(
- !BUILD_EXISTS,
- `Main build missing at ${MAIN_ENTRY} β€” run "bun run build:desktop" first.`,
- );
+ test.skip(!TARGET.exists, TARGET.missingReason);
test.afterEach(async () => {
for (const target of cleanupTargets.splice(0)) {
diff --git a/packages/desktop/tests/smoke/create-new-project.e2e.ts b/packages/desktop/tests/smoke/create-new-project.e2e.ts
index 5daf69a59..2239d1bf1 100644
--- a/packages/desktop/tests/smoke/create-new-project.e2e.ts
+++ b/packages/desktop/tests/smoke/create-new-project.e2e.ts
@@ -47,20 +47,18 @@ import {
writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import type { ElectronApplication, Page } from '@playwright/test';
import { _electron as electron } from '@playwright/test';
import { typeProjectName } from './_helpers/create-new-dialog';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { clickNavCreateNew } from './_helpers/navigator-actions';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
const DESKTOP_PRODUCT_NAME = '@inkeep/open-knowledge-desktop';
@@ -102,18 +100,20 @@ async function launchApp(tmpHome: string, opts: LaunchOpts = {}): Promise<Electr
// app.getPath('userData') on macOS β€” setting HOME doesn't work because
// NSHomeDirectory() resolves via getpwuid(), not the env.
const userDataDir = join(tmpHome, 'Library', 'Application Support', DESKTOP_PRODUCT_NAME);
- return electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${userDataDir}`],
- timeout: 30_000,
- env: {
- ...process.env,
- HOME: tmpHome,
- OK_DESKTOP_E2E_SMOKE: '1',
- ...(opts.pickedParent !== undefined
- ? { OK_DESKTOP_TEST_PICKED_PATH: opts.pickedParent }
- : {}),
- },
- });
+ return electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${userDataDir}`],
+ env: {
+ ...process.env,
+ HOME: tmpHome,
+ OK_DESKTOP_E2E_SMOKE: '1',
+ ...(opts.pickedParent !== undefined
+ ? { OK_DESKTOP_TEST_PICKED_PATH: opts.pickedParent }
+ : {}),
+ },
+ }),
+ );
}
async function findWindowByMode(
@@ -162,10 +162,7 @@ function trackForCleanup(...paths: string[]): void {
test.describe('Create-new-project smoke', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'Smoke harness is darwin-only.');
- test.skip(
- !BUILD_EXISTS,
- `Main build missing at ${MAIN_ENTRY} β€” run "bun run build:desktop" first.`,
- );
+ test.skip(!TARGET.exists, TARGET.missingReason);
test.afterEach(async () => {
for (const target of cleanupTargets.splice(0)) {
diff --git a/packages/desktop/tests/smoke/deep-link.e2e.ts b/packages/desktop/tests/smoke/deep-link.e2e.ts
index 0c625971d..bd9bc1dc9 100644
--- a/packages/desktop/tests/smoke/deep-link.e2e.ts
+++ b/packages/desktop/tests/smoke/deep-link.e2e.ts
@@ -22,28 +22,26 @@
* - Not on macOS (`process.platform !== 'darwin'`) β€” the `open` command
* is macOS-specific, and the URL-scheme handler is darwin-only in v0.
* - Main-process build output missing (`out/main/index.js` absent) β€” the
- * app must be built via `bun run build:desktop` before this test runs.
+ * app must be built via `pnpm run build:desktop` before this test runs.
* CI runs without a pre-build skip gracefully rather than misreporting.
- * - `OK_DESKTOP_E2E_SMOKE !== '1'` β€” gate so `bunx playwright test` on the
+ * - `OK_DESKTOP_E2E_SMOKE !== '1'` β€” gate so `pnpm exec playwright test` on the
* entire repo without explicit opt-in doesn't attempt to launch Electron
* (which crashes headless CI that lacks a display server).
*/
import { execSync } from 'node:child_process';
-import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import { _electron as electron } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
// Environment gate: opt-in only. Default-off keeps the test harmless on CI.
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
// Compute a per-test Electron userData dir under tmpHome. The Chromium
// `--user-data-dir=<path>` switch is the only mechanism that reliably
@@ -61,10 +59,7 @@ function userDataDirFor(tmpHome: string): string {
test.describe('deep-link warm-start smoke (M4 US-009 / AC7)', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'Deep-link URL scheme is macOS-only in v0 (D51 NOT NOW).');
- test.skip(
- !BUILD_EXISTS,
- `Main build missing at ${MAIN_ENTRY} β€” run "bun run build:desktop" first.`,
- );
+ test.skip(!TARGET.exists, TARGET.missingReason);
// Explicit visibility of the coverage gap β€” appears in test-run output as
// a named skip so the missing coverage can't be overlooked when scanning
@@ -100,10 +95,13 @@ test.describe('deep-link warm-start smoke (M4 US-009 / AC7)', () => {
);
writeFileSync(join(projectDir, 'target.md'), '# Target Doc\n\nDeep-link smoke content.\n');
- const app = await electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${userDataDirFor(tmpHome)}`],
- timeout: 30_000,
- });
+ const app = await electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${userDataDirFor(tmpHome)}`],
+ timeout: 30_000,
+ }),
+ );
captureStderrFor(app, { cleanupDirs: [projectDir, tmpHome] });
// Wait for the first window to appear β€” the Navigator spawns at boot in
@@ -153,10 +151,13 @@ test.describe('deep-link warm-start smoke (M4 US-009 / AC7)', () => {
'# Meeting Notes\n\nNested doc smoke.\n',
);
- const app = await electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${userDataDirFor(tmpHome)}`],
- timeout: 30_000,
- });
+ const app = await electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${userDataDirFor(tmpHome)}`],
+ timeout: 30_000,
+ }),
+ );
captureStderrFor(app, { cleanupDirs: [projectDir, tmpHome] });
const firstWindow = await app.firstWindow({ timeout: 15_000 });
diff --git a/packages/desktop/tests/smoke/external-link.e2e.ts b/packages/desktop/tests/smoke/external-link.e2e.ts
index 11efdff2c..a2d0c128f 100644
--- a/packages/desktop/tests/smoke/external-link.e2e.ts
+++ b/packages/desktop/tests/smoke/external-link.e2e.ts
@@ -9,26 +9,21 @@
* Skip conditions match deep-link.e2e.ts.
*/
-import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import { _electron as electron } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
test.describe('external-link safety-net delegation', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'Smoke uses open(1) for the deep-link drive β€” macOS-only.');
- test.skip(
- !BUILD_EXISTS,
- `Main build missing at ${MAIN_ENTRY} β€” run "bun run build:desktop" first.`,
- );
+ test.skip(!TARGET.exists, TARGET.missingReason);
test('window.open(https://...) routes to shell.openExternal via safety net', async ({
captureStderrFor,
@@ -50,14 +45,17 @@ test.describe('external-link safety-net delegation', () => {
// instead of letting `OK_TEST_OPEN_PROJECT` drive the project β€” same
// mechanism documented in deep-link.e2e.ts:53. The dir lands under the
// test's `projectDir` tmpdir so the fixture's `cleanupDirs` covers it.
- const app = await electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${join(projectDir, 'electron-userdata')}`],
- timeout: 30_000,
- env: {
- ...process.env,
- OK_TEST_OPEN_PROJECT: projectDir,
- },
- });
+ const app = await electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${join(projectDir, 'electron-userdata')}`],
+ timeout: 30_000,
+ env: {
+ ...process.env,
+ OK_TEST_OPEN_PROJECT: projectDir,
+ },
+ }),
+ );
captureStderrFor(app, { cleanupDirs: [projectDir] });
// Tap into the main process β€” install a stub for shell.openExternal that
diff --git a/packages/desktop/tests/smoke/mcp-wiring.e2e.ts b/packages/desktop/tests/smoke/mcp-wiring.e2e.ts
index 926cfaba2..5762051f6 100644
--- a/packages/desktop/tests/smoke/mcp-wiring.e2e.ts
+++ b/packages/desktop/tests/smoke/mcp-wiring.e2e.ts
@@ -31,10 +31,10 @@
* same gate blocking the signed-DMG scenarios. Not executable from this test file.
*
* Skip gates mirror `deep-link.e2e.ts`:
- * - `OK_DESKTOP_E2E_SMOKE !== '1'` β€” opt-in so `bunx playwright test` on the
+ * - `OK_DESKTOP_E2E_SMOKE !== '1'` β€” opt-in so `pnpm exec playwright test` on the
* whole repo doesn't try to launch Electron in headless CI.
* - `process.platform !== 'darwin'` β€” gates on darwin.
- * - `out/main/index.js` missing β€” `bun run build:desktop` must have run.
+ * - `out/main/index.js` missing β€” `pnpm run build:desktop` must have run.
*/
import {
@@ -47,18 +47,16 @@ import {
writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import type { ElectronApplication, Page } from '@playwright/test';
import { _electron as electron } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
interface LaunchOpts {
tmpHome: string;
@@ -76,17 +74,25 @@ function userDataDirFor(tmpHome: string): string {
}
async function launchApp({ tmpHome, extraEnv }: LaunchOpts): Promise<ElectronApplication> {
- return electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${userDataDirFor(tmpHome)}`],
- timeout: 30_000,
- env: {
- ...process.env,
- HOME: tmpHome,
- OK_M6B_FORCE: '1',
- OK_DESKTOP_E2E_SMOKE: '1',
- ...extraEnv,
- },
- });
+ return electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${userDataDirFor(tmpHome)}`],
+ env: {
+ ...process.env,
+ HOME: tmpHome,
+ // A no-op when the target is packaged (the bypass reads
+ // `app.isPackaged || OK_M6B_FORCE === '1'`), so it is safe in both
+ // modes. Notably NOT paired with OK_RECLAIM_DISABLE:
+ // `runMcpWiringOnFirstLaunch` returns an inert handle on that variable
+ // before it ever reaches the packaged gate, which would make every
+ // consent-dialog assertion below vacuous.
+ OK_M6B_FORCE: '1',
+ OK_DESKTOP_E2E_SMOKE: '1',
+ ...extraEnv,
+ },
+ }),
+ );
}
function createTmpHome(prefix: string): string {
@@ -165,10 +171,7 @@ function forceRemove(pathsToRestore: readonly string[], dir: string): void {
test.describe('M6b first-launch MCP-wiring smoke (US-010)', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'M6b is macOS-only in v0 (D51 / D-M6-R7).');
- test.skip(
- !BUILD_EXISTS,
- `Main build missing at ${MAIN_ENTRY} β€” run "bun run build:desktop" first.`,
- );
+ test.skip(!TARGET.exists, TARGET.missingReason);
// Cold-start `openknowledge://` delivery to a deep-link-opened editor
// window as the FIRST window. Deferred until signed DMG enables Launch
diff --git a/packages/desktop/tests/smoke/navigator-close-on-open.e2e.ts b/packages/desktop/tests/smoke/navigator-close-on-open.e2e.ts
index a8f21b8f9..81705e783 100644
--- a/packages/desktop/tests/smoke/navigator-close-on-open.e2e.ts
+++ b/packages/desktop/tests/smoke/navigator-close-on-open.e2e.ts
@@ -21,23 +21,21 @@
* Skip gates mirror the rest of the smoke harness:
* - `OK_DESKTOP_E2E_SMOKE !== '1'` β€” opt-in.
* - `process.platform !== 'darwin'` β€” darwin-only in v0.
- * - `out/main/index.js` missing β€” `bun run build:desktop` must have run.
+ * - `out/main/index.js` missing β€” `pnpm run build:desktop` must have run.
*/
-import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import type { ElectronApplication, Page } from '@playwright/test';
import { _electron as electron } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
interface SeededHome {
tmpHome: string;
@@ -116,15 +114,18 @@ function seedHomeWithLastOpenedProjectAndExtra(prefix: string): SeededHomeWithEd
}
async function launchApp(tmpHome: string): Promise<ElectronApplication> {
- return electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${userDataDirFor(tmpHome)}`],
- timeout: 30_000,
- env: {
- ...process.env,
- HOME: tmpHome,
- OK_DESKTOP_E2E_SMOKE: '1',
- },
- });
+ return electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${userDataDirFor(tmpHome)}`],
+ timeout: 30_000,
+ env: {
+ ...process.env,
+ HOME: tmpHome,
+ OK_DESKTOP_E2E_SMOKE: '1',
+ },
+ }),
+ );
}
async function countWindowsByMode(
@@ -157,10 +158,7 @@ async function findFirstWindowByMode(
test.describe('Project Navigator close-on-project-open smoke', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'Smoke harness is darwin-only in v0.');
- test.skip(
- !BUILD_EXISTS,
- `Main build missing at ${MAIN_ENTRY} β€” run "bun run build:desktop" first.`,
- );
+ test.skip(!TARGET.exists, TARGET.missingReason);
test('Navigator boots first, closes once a project window resolves', async ({
captureStderrFor,
diff --git a/packages/desktop/tests/smoke/navigator-return.e2e.ts b/packages/desktop/tests/smoke/navigator-return.e2e.ts
index d09c2e910..f421fb43f 100644
--- a/packages/desktop/tests/smoke/navigator-return.e2e.ts
+++ b/packages/desktop/tests/smoke/navigator-return.e2e.ts
@@ -17,31 +17,29 @@
* rather than clicking the dropdown trigger β€” exercising the IPC contract is
* the goal here; full DOM-driven affordance coverage (dropdown click,
* CommandPalette `Cmd+K` keystroke) belongs to component-level Playwright
- * runs that also need the `bun run dev` server, not the smoke harness.
+ * runs that also need the `pnpm dev` server, not the smoke harness.
*
* Skip gates mirror `deep-link.e2e.ts` and `mcp-wiring.e2e.ts`:
- * - `OK_DESKTOP_E2E_SMOKE !== '1'` β€” opt-in so `bunx playwright test` on
+ * - `OK_DESKTOP_E2E_SMOKE !== '1'` β€” opt-in so `pnpm exec playwright test` on
* the whole repo doesn't try to launch Electron in headless CI.
* - `process.platform !== 'darwin'` β€” the smoke harness is darwin-only in
* v0; the IPC plumbing is platform-agnostic and remains exercised by the
* Bun unit/integration tests on every platform.
- * - `out/main/index.js` missing β€” `bun run build:desktop` must have run.
+ * - `out/main/index.js` missing β€” `pnpm run build:desktop` must have run.
*/
-import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import type { ElectronApplication, Page } from '@playwright/test';
import { _electron as electron } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
interface SeededHome {
tmpHome: string;
@@ -90,15 +88,18 @@ function seedHomeWithLastOpenedProject(prefix: string): SeededHome {
}
async function launchApp(tmpHome: string): Promise<ElectronApplication> {
- return electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${userDataDirFor(tmpHome)}`],
- timeout: 30_000,
- env: {
- ...process.env,
- HOME: tmpHome,
- OK_DESKTOP_E2E_SMOKE: '1',
- },
- });
+ return electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${userDataDirFor(tmpHome)}`],
+ timeout: 30_000,
+ env: {
+ ...process.env,
+ HOME: tmpHome,
+ OK_DESKTOP_E2E_SMOKE: '1',
+ },
+ }),
+ );
}
async function findEditorWindow(app: ElectronApplication, timeoutMs = 20_000): Promise<Page> {
@@ -165,10 +166,7 @@ async function findNavigatorWindow(app: ElectronApplication, timeoutMs = 15_000)
test.describe('Project Navigator return-affordance smoke', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'Smoke harness is darwin-only in v0.');
- test.skip(
- !BUILD_EXISTS,
- `Main build missing at ${MAIN_ENTRY} β€” run "bun run build:desktop" first.`,
- );
+ test.skip(!TARGET.exists, TARGET.missingReason);
test('bridge.navigator.open() opens navigator from editor; re-invokes never spawn a duplicate', async ({
captureStderrFor,
diff --git a/packages/desktop/tests/smoke/qa-create-new-extended.e2e.ts b/packages/desktop/tests/smoke/qa-create-new-extended.e2e.ts
index 61eff1cff..35f3feb4c 100644
--- a/packages/desktop/tests/smoke/qa-create-new-extended.e2e.ts
+++ b/packages/desktop/tests/smoke/qa-create-new-extended.e2e.ts
@@ -29,21 +29,19 @@ import {
writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import type { ElectronApplication, Page } from '@playwright/test';
import { _electron as electron } from '@playwright/test';
import { typeProjectName } from './_helpers/create-new-dialog';
import { captureAppProcess, closeAppBounded } from './_helpers/electron-cleanup';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { clickNavCreateNew } from './_helpers/navigator-actions';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
const DESKTOP_PRODUCT_NAME = '@inkeep/open-knowledge-desktop';
/**
@@ -86,18 +84,21 @@ interface LaunchOpts {
async function launchApp(tmpHome: string, opts: LaunchOpts = {}): Promise<ElectronApplication> {
const userDataDir = join(tmpHome, 'Library', 'Application Support', DESKTOP_PRODUCT_NAME);
- return electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${userDataDir}`],
- timeout: 30_000,
- env: {
- ...process.env,
- HOME: tmpHome,
- OK_DESKTOP_E2E_SMOKE: '1',
- ...(opts.pickedParent !== undefined
- ? { OK_DESKTOP_TEST_PICKED_PATH: opts.pickedParent }
- : {}),
- },
- });
+ return electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${userDataDir}`],
+ timeout: 30_000,
+ env: {
+ ...process.env,
+ HOME: tmpHome,
+ OK_DESKTOP_E2E_SMOKE: '1',
+ ...(opts.pickedParent !== undefined
+ ? { OK_DESKTOP_TEST_PICKED_PATH: opts.pickedParent }
+ : {}),
+ },
+ }),
+ );
}
async function findWindowByMode(
@@ -146,7 +147,7 @@ function trackForCleanup(...paths: string[]): void {
test.describe('QA extended create-new-project', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run.');
test.skip(!DARWIN, 'Darwin-only.');
- test.skip(!BUILD_EXISTS, 'Run "bun run build:desktop" first.');
+ test.skip(!TARGET.exists, TARGET.missingReason);
test.afterEach(async () => {
for (const target of cleanupTargets.splice(0)) {
diff --git a/packages/desktop/tests/smoke/rename-divergence-probe.e2e.ts b/packages/desktop/tests/smoke/rename-divergence-probe.e2e.ts
index 400790f1e..ccf07ec43 100644
--- a/packages/desktop/tests/smoke/rename-divergence-probe.e2e.ts
+++ b/packages/desktop/tests/smoke/rename-divergence-probe.e2e.ts
@@ -30,14 +30,13 @@
import { randomUUID } from 'node:crypto';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { join } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
-import { fileURLToPath } from 'node:url';
import { type ElectronApplication, _electron as electron } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
@@ -69,7 +68,7 @@ async function runProbe(
): Promise<ProbeOutcome> {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'Driver uses macOS open(1).');
- test.skip(!existsSync(MAIN_ENTRY), `out/main/index.js missing β€” run \`bun run build:desktop\`.`);
+ test.skip(!TARGET.exists, TARGET.missingReason);
// Fresh isolated everything
const contentDir = mkdtempSync(join(tmpdir(), `ok-rename-probe-${variant}-`));
@@ -91,11 +90,14 @@ async function runProbe(
// doesn't fire open-url Apple Event, but main process parses argv URLs
// for first-instance β€” confirmed by the packaged .app working earlier
// with the same args shape).
- const app = await electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${userDataDir}`, deepLink],
- env: { ...process.env, NODE_ENV: 'production' },
- timeout: 30_000,
- });
+ const app = await electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${userDataDir}`, deepLink],
+ env: { ...process.env, NODE_ENV: 'production' },
+ timeout: 30_000,
+ }),
+ );
// Registers BOTH the stderr-capture and the bounded-cleanup contract.
// The fixture's teardown reaps the Electron process group within a
// ~5s budget β€” the test body must not call `app.close()` itself
diff --git a/packages/desktop/tests/smoke/report-bug.e2e.ts b/packages/desktop/tests/smoke/report-bug.e2e.ts
index d1f312555..57b32dc4e 100644
--- a/packages/desktop/tests/smoke/report-bug.e2e.ts
+++ b/packages/desktop/tests/smoke/report-bug.e2e.ts
@@ -26,7 +26,6 @@
*/
import {
- existsSync,
mkdirSync,
mkdtempSync,
readdirSync,
@@ -35,26 +34,21 @@ import {
writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import type { Page } from '@playwright/test';
import { _electron as electron } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
test.describe('Report-a-bug entry points', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'Smoke harness is darwin-only.');
- test.skip(
- !BUILD_EXISTS,
- `Main build missing at ${MAIN_ENTRY} β€” run "bun run build:desktop" first.`,
- );
+ test.skip(!TARGET.exists, TARGET.missingReason);
test('Help menu and palette open the dialog; create lands a zip shown in review', async ({
captureStderrFor,
@@ -87,15 +81,18 @@ test.describe('Report-a-bug entry points', () => {
}),
);
- const app = await electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${userDataDir}`],
- timeout: 30_000,
- env: {
- ...process.env,
- HOME: tmpHome,
- OK_DESKTOP_E2E_SMOKE: '1',
- },
- });
+ const app = await electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${userDataDir}`],
+ timeout: 30_000,
+ env: {
+ ...process.env,
+ HOME: tmpHome,
+ OK_DESKTOP_E2E_SMOKE: '1',
+ },
+ }),
+ );
captureStderrFor(app, { cleanupDirs: [tmpHome, projectDir] });
let editorPage: Page | undefined;
diff --git a/packages/desktop/tests/smoke/share-receive-miss-terminal.e2e.ts b/packages/desktop/tests/smoke/share-receive-miss-terminal.e2e.ts
index 7e5b2adfb..7aaa25a49 100644
--- a/packages/desktop/tests/smoke/share-receive-miss-terminal.e2e.ts
+++ b/packages/desktop/tests/smoke/share-receive-miss-terminal.e2e.ts
@@ -31,19 +31,17 @@
import { execFileSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
-import { existsSync, mkdirSync, mkdtempSync, realpathSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, realpathSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import { _electron as electron } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
function git(cwd: string, ...args: string[]): void {
execFileSync('git', args, {
@@ -102,10 +100,7 @@ function setupDeletedTargetFixture(): MissFixture {
test.describe('share-receive miss terminal smoke', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'Deep-link URL scheme is macOS-only in v0.');
- test.skip(
- !BUILD_EXISTS,
- `Main build missing at ${MAIN_ENTRY} β€” run "bun run build:desktop" first.`,
- );
+ test.skip(!TARGET.exists, TARGET.missingReason);
test('a deleted share target lands the receiver on the miss dialog, never create-mode', async ({
captureStderrFor,
@@ -134,10 +129,13 @@ test.describe('share-receive miss terminal smoke', () => {
const githubBlobUrl = `https://github.com/inkeep/open-knowledge/blob/main/${fixture.docPath}`;
const shareUrl = `openknowledge://share?url=${encodeURIComponent(githubBlobUrl)}`;
- const app = await electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${userData}`, shareUrl],
- timeout: 30_000,
- });
+ const app = await electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${userData}`, shareUrl],
+ timeout: 30_000,
+ }),
+ );
captureStderrFor(app, { cleanupDirs: [fixture.root, tmpHome] });
const firstWindow = await app.firstWindow({ timeout: 15_000 });
diff --git a/packages/desktop/tests/smoke/share-receive-multi-worktree.e2e.ts b/packages/desktop/tests/smoke/share-receive-multi-worktree.e2e.ts
index ac335b3d1..c4a1578e3 100644
--- a/packages/desktop/tests/smoke/share-receive-multi-worktree.e2e.ts
+++ b/packages/desktop/tests/smoke/share-receive-multi-worktree.e2e.ts
@@ -37,19 +37,17 @@
*/
import { execSync } from 'node:child_process';
-import { existsSync, mkdirSync, mkdtempSync, realpathSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, realpathSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import { _electron as electron } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
function userDataDirFor(tmpHome: string): string {
return join(tmpHome, 'electron-userdata');
@@ -127,10 +125,7 @@ function setupMultiWorktree(): MultiWorktreeFixture {
test.describe('share-receive multi-worktree smoke (US-014 / J1 silent dispatch)', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'Deep-link URL scheme is macOS-only in v0.');
- test.skip(
- !BUILD_EXISTS,
- `Main build missing at ${MAIN_ENTRY} β€” run "bun run build:desktop" first.`,
- );
+ test.skip(!TARGET.exists, TARGET.missingReason);
// Deferred (same harness limitation as the J2/J5 cases below and
// deep-link.e2e.ts's cold-start path): the share-receive dispatch never
@@ -176,10 +171,13 @@ test.describe('share-receive multi-worktree smoke (US-014 / J1 silent dispatch)'
};
writeFileSync(join(userData, 'Electron', 'state.json'), JSON.stringify(recentsState, null, 2));
- const app = await electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${userData}`],
- timeout: 30_000,
- });
+ const app = await electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${userData}`],
+ timeout: 30_000,
+ }),
+ );
// cleanupDirs handles tmpdir removal after the Electron process group is
// reaped; fixture.root is one of those dirs so the dedicated cleanup()
// helper is redundant here. Keep the helper for callers that need
diff --git a/packages/desktop/tests/smoke/sidebar-create-rename-editable.e2e.ts b/packages/desktop/tests/smoke/sidebar-create-rename-editable.e2e.ts
index 31050b49d..2e43b8690 100644
--- a/packages/desktop/tests/smoke/sidebar-create-rename-editable.e2e.ts
+++ b/packages/desktop/tests/smoke/sidebar-create-rename-editable.e2e.ts
@@ -5,28 +5,16 @@
import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import type { ElectronApplication, Page } from '@playwright/test';
import { _electron as electron } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const PACKAGED_EXECUTABLE = resolve(
- __dirname,
- '..',
- '..',
- 'dist-desktop',
- 'mac-arm64',
- 'OpenKnowledge.app',
- 'Contents',
- 'MacOS',
- 'OpenKnowledge',
-);
+const TARGET = resolveDesktopTarget({ requirePackaged: true });
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const PACKAGED_BUILD_EXISTS = existsSync(PACKAGED_EXECUTABLE);
interface SeededProject {
tmpHome: string;
@@ -71,18 +59,20 @@ function seedProject(prefix: string): SeededProject {
async function launchApp(seed: SeededProject): Promise<ElectronApplication> {
const deepLink = `openknowledge://open?project=${encodeURIComponent(seed.projectDir)}&doc=start`;
const args = [`--user-data-dir=${seed.userDataDir}`, deepLink];
- return electron.launch({
- executablePath: PACKAGED_EXECUTABLE,
- args,
- timeout: 30_000,
- env: {
- ...process.env,
- HOME: seed.tmpHome,
- OK_DESKTOP_E2E_SMOKE: '1',
- OK_RECLAIM_DISABLE: '1',
- NODE_ENV: 'production',
- },
- });
+ return electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args,
+ timeout: 30_000,
+ env: {
+ ...process.env,
+ HOME: seed.tmpHome,
+ OK_DESKTOP_E2E_SMOKE: '1',
+ OK_RECLAIM_DISABLE: '1',
+ NODE_ENV: 'production',
+ },
+ }),
+ );
}
async function findEditorWindow(app: ElectronApplication, docName: string): Promise<Page> {
@@ -152,10 +142,7 @@ async function createSidebarFileAndType(
test.describe('Sidebar create and rename editability smoke', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'Smoke harness is darwin-only in v0.');
- test.skip(
- !PACKAGED_BUILD_EXISTS,
- `Packaged desktop build missing at ${PACKAGED_EXECUTABLE} β€” run an unpacked packaged build first.`,
- );
+ test.skip(!TARGET.exists, TARGET.missingReason);
test('successive sidebar-created files remain editable after inline rename commit', async ({
captureStderrFor,
diff --git a/packages/desktop/tests/smoke/sidebar-pill-lockstep-fade.e2e.ts b/packages/desktop/tests/smoke/sidebar-pill-lockstep-fade.e2e.ts
index 44f2a8843..27540c436 100644
--- a/packages/desktop/tests/smoke/sidebar-pill-lockstep-fade.e2e.ts
+++ b/packages/desktop/tests/smoke/sidebar-pill-lockstep-fade.e2e.ts
@@ -32,19 +32,17 @@
import { execSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
-import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import { _electron as electron } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
function userDataDirFor(home: string): string {
return join(home, 'electron-userdata');
@@ -66,7 +64,7 @@ async function expectDocument(
test.describe('sidebar search pill β€” Electron lockstep-fade smoke', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'Driver uses macOS open(1) and chrome stack is darwin-only in v0.');
- test.skip(!BUILD_EXISTS, `Main build missing at ${MAIN_ENTRY} β€” run "pnpm build:desktop" first.`);
+ test.skip(!TARGET.exists, TARGET.missingReason);
test('navigation controls relocate on collapse while sidebar chrome fades in lockstep', async ({
captureStderrFor,
@@ -93,10 +91,13 @@ test.describe('sidebar search pill β€” Electron lockstep-fade smoke', () => {
`# ${secondMarker}\n\nFixture for browser-history traversal.\n`,
);
- const app = await electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${userDataDirFor(projectDir)}`],
- timeout: 30_000,
- });
+ const app = await electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${userDataDirFor(projectDir)}`],
+ timeout: 30_000,
+ }),
+ );
captureStderrFor(app, { cleanupDirs: [projectDir] });
// Wait for Navigator (cold-launch first window).
diff --git a/packages/desktop/tests/smoke/terminal-dock.e2e.ts b/packages/desktop/tests/smoke/terminal-dock.e2e.ts
index c0022f018..b4bcbd0e3 100644
--- a/packages/desktop/tests/smoke/terminal-dock.e2e.ts
+++ b/packages/desktop/tests/smoke/terminal-dock.e2e.ts
@@ -31,18 +31,16 @@ import {
writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import type { ElectronApplication, Page } from '@playwright/test';
import { _electron as electron } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
// Quarantine gate β€” see the header. Allowlisted in the CI no-skip guard so the
// skip stays gate-visible.
const IS_CI = process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true';
@@ -169,21 +167,24 @@ async function launchApp(s: Seed, opts: LaunchOpts = {}): Promise<ElectronApplic
// ~/.local/bin). The fake-claude prefix, when present, is prepended.
const basePath = opts.restrictPath ? '/usr/bin:/bin:/usr/sbin:/sbin' : (process.env.PATH ?? '');
const PATH = s.pathPrefix ? `${s.pathPrefix}:${basePath}` : basePath;
- return electron.launch({
- // No --disable-gpu: blanket software rendering starves CPU on constrained CI
- // runners. Instead TerminalPanel forces xterm's DOM renderer (not WebGL) when
- // the e2eSmoke config flag is set (from OK_DESKTOP_E2E_SMOKE=1, below), so
- // these DOM-based assertions can read the terminal while Electron keeps GPU.
- args: [MAIN_ENTRY, `--user-data-dir=${s.userDataDir}`, deepLink],
- timeout: 30_000,
- env: {
- ...process.env,
- HOME: s.tmpHome,
- PATH,
- OK_DESKTOP_E2E_SMOKE: '1',
- OK_RECLAIM_DISABLE: '1',
- },
- });
+ return electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ // No --disable-gpu: blanket software rendering starves CPU on constrained CI
+ // runners. Instead TerminalPanel forces xterm's DOM renderer (not WebGL) when
+ // the e2eSmoke config flag is set (from OK_DESKTOP_E2E_SMOKE=1, below), so
+ // these DOM-based assertions can read the terminal while Electron keeps GPU.
+ args: [`--user-data-dir=${s.userDataDir}`, deepLink],
+ timeout: 30_000,
+ env: {
+ ...process.env,
+ HOME: s.tmpHome,
+ PATH,
+ OK_DESKTOP_E2E_SMOKE: '1',
+ OK_RECLAIM_DISABLE: '1',
+ },
+ }),
+ );
}
async function findEditorWindow(app: ElectronApplication, timeoutMs = 25_000): Promise<Page> {
@@ -288,7 +289,7 @@ function track(...paths: string[]): void {
test.describe('Docked terminal β€” live Electron', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'Desktop is darwin-only.');
- test.skip(!BUILD_EXISTS, `Main build missing at ${MAIN_ENTRY} β€” run "bun run build:desktop".`);
+ test.skip(!TARGET.exists, TARGET.missingReason);
// Quarantined on CI (shells exit before "running" on the constrained 6-vCPU
// runner; passes locally). Tracked via the QUARANTINE_ALLOWLIST in the CI
// no-skip guard, not hidden.
diff --git a/packages/desktop/tests/smoke/terminal-links.e2e.ts b/packages/desktop/tests/smoke/terminal-links.e2e.ts
index b9a66ffe9..7e07bb940 100644
--- a/packages/desktop/tests/smoke/terminal-links.e2e.ts
+++ b/packages/desktop/tests/smoke/terminal-links.e2e.ts
@@ -20,28 +20,18 @@
* (QUARANTINE_ALLOWLIST); tracked in inkeep/agents-private#2187.
*/
-import {
- chmodSync,
- existsSync,
- mkdirSync,
- mkdtempSync,
- realpathSync,
- rmSync,
- writeFileSync,
-} from 'node:fs';
+import { chmodSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import type { ElectronApplication, Page } from '@playwright/test';
import { _electron as electron } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
const IS_CI = process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true';
const DESKTOP_PRODUCT_NAME = '@inkeep/open-knowledge-desktop';
@@ -89,21 +79,23 @@ function seed(prefix: string): Seed {
async function launchApp(s: Seed): Promise<ElectronApplication> {
const deepLink = `openknowledge://open?project=${encodeURIComponent(s.projectDir)}&doc=start`;
- return electron.launch({
- args: [
- MAIN_ENTRY,
- `--user-data-dir=${join(s.tmpHome, 'Library', 'Application Support', DESKTOP_PRODUCT_NAME)}`,
- deepLink,
- ],
- timeout: 30_000,
- env: {
- ...process.env,
- HOME: s.tmpHome,
- PATH: `${s.pathPrefix}:${process.env.PATH ?? ''}`,
- OK_DESKTOP_E2E_SMOKE: '1',
- OK_RECLAIM_DISABLE: '1',
- },
- });
+ return electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [
+ `--user-data-dir=${join(s.tmpHome, 'Library', 'Application Support', DESKTOP_PRODUCT_NAME)}`,
+ deepLink,
+ ],
+ timeout: 30_000,
+ env: {
+ ...process.env,
+ HOME: s.tmpHome,
+ PATH: `${s.pathPrefix}:${process.env.PATH ?? ''}`,
+ OK_DESKTOP_E2E_SMOKE: '1',
+ OK_RECLAIM_DISABLE: '1',
+ },
+ }),
+ );
}
async function findEditorWindow(app: ElectronApplication, timeoutMs = 25_000): Promise<Page> {
@@ -199,8 +191,8 @@ function track(...paths: string[]): void {
test.describe('Terminal clickable links β€” live Electron', () => {
test.skip(
- !SMOKE_ENABLED || !DARWIN || !BUILD_EXISTS,
- 'Live-Electron smoke: set OK_DESKTOP_E2E_SMOKE=1 on darwin after `bun run build:desktop`.',
+ !SMOKE_ENABLED || !DARWIN || !TARGET.exists,
+ `Live-Electron smoke: set OK_DESKTOP_E2E_SMOKE=1 on darwin. ${TARGET.missingReason}`,
);
test.skip(
IS_CI,
diff --git a/packages/desktop/tests/smoke/terminal-tabs.e2e.ts b/packages/desktop/tests/smoke/terminal-tabs.e2e.ts
index f21140595..f10f8aceb 100644
--- a/packages/desktop/tests/smoke/terminal-tabs.e2e.ts
+++ b/packages/desktop/tests/smoke/terminal-tabs.e2e.ts
@@ -22,23 +22,21 @@
* darwin-only, the electron-vite build must exist (out/main/index.js), and
* CI-quarantined (the live-Electron terminal surface degrades on the constrained
* runner β€” allowlisted in the CI no-skip guard, not hidden). Runs in local dev /
- * the release gate. Not part of `bun run check`.
+ * the release gate. Not part of `pnpm check`.
*/
-import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import type { ElectronApplication, Page } from '@playwright/test';
import { _electron as electron } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
const IS_CI = process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true';
const DESKTOP_PRODUCT_NAME = '@inkeep/open-knowledge-desktop';
@@ -80,17 +78,20 @@ async function launchApp(s: Seed): Promise<ElectronApplication> {
// Restricted, system-only PATH: the New-chat carat opens a BARE shell (the
// "Terminal" pick) so no `claude` install is needed to spawn a live PTY.
const PATH = '/usr/bin:/bin:/usr/sbin:/sbin';
- return electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${s.userDataDir}`, deepLink],
- timeout: 30_000,
- env: {
- ...process.env,
- HOME: s.tmpHome,
- PATH,
- OK_DESKTOP_E2E_SMOKE: '1',
- OK_RECLAIM_DISABLE: '1',
- },
- });
+ return electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${s.userDataDir}`, deepLink],
+ timeout: 30_000,
+ env: {
+ ...process.env,
+ HOME: s.tmpHome,
+ PATH,
+ OK_DESKTOP_E2E_SMOKE: '1',
+ OK_RECLAIM_DISABLE: '1',
+ },
+ }),
+ );
}
async function findEditorWindow(app: ElectronApplication, timeoutMs = 25_000): Promise<Page> {
@@ -214,7 +215,7 @@ function track(...paths: string[]): void {
test.describe('Terminal tabs β€” live Electron', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'Desktop is darwin-only.');
- test.skip(!BUILD_EXISTS, `Main build missing at ${MAIN_ENTRY} β€” run "bun run build:desktop".`);
+ test.skip(!TARGET.exists, TARGET.missingReason);
test.skip(
IS_CI,
'Quarantined on CI: the live-Electron terminal surface degrades on the constrained runner β€” see inkeep/agents-private#2187.',
diff --git a/packages/desktop/tests/smoke/terminal-window.e2e.ts b/packages/desktop/tests/smoke/terminal-window.e2e.ts
index dada1c853..176f1c587 100644
--- a/packages/desktop/tests/smoke/terminal-window.e2e.ts
+++ b/packages/desktop/tests/smoke/terminal-window.e2e.ts
@@ -13,24 +13,22 @@
* darwin-only, the electron-vite build must exist, and CI-skipped (the
* live-Electron terminal surface is not yet validated on the CI runner β€” same
* caveat as the docked-terminal smoke). Runs in local dev to keep the seam
- * covered. Not part of `bun run check`; run via `bunx playwright test` or
- * `bun run check:full:parallel`.
+ * covered. Not part of `pnpm check`; run via `pnpm exec playwright test` or
+ * `pnpm run check:full:parallel`.
*/
-import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import type { ElectronApplication, Page } from '@playwright/test';
import { _electron as electron } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
const IS_CI = process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true';
const DESKTOP_PRODUCT_NAME = '@inkeep/open-knowledge-desktop';
@@ -69,17 +67,20 @@ function seed(prefix: string): Seed {
async function launchApp(s: Seed): Promise<ElectronApplication> {
const deepLink = `openknowledge://open?project=${encodeURIComponent(s.projectDir)}&doc=start`;
- return electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${s.userDataDir}`, deepLink],
- timeout: 30_000,
- env: {
- ...process.env,
- HOME: s.tmpHome,
- PATH: '/usr/bin:/bin:/usr/sbin:/sbin',
- OK_DESKTOP_E2E_SMOKE: '1',
- OK_RECLAIM_DISABLE: '1',
- },
- });
+ return electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${s.userDataDir}`, deepLink],
+ timeout: 30_000,
+ env: {
+ ...process.env,
+ HOME: s.tmpHome,
+ PATH: '/usr/bin:/bin:/usr/sbin:/sbin',
+ OK_DESKTOP_E2E_SMOKE: '1',
+ OK_RECLAIM_DISABLE: '1',
+ },
+ }),
+ );
}
async function findWindowByMode(
@@ -130,7 +131,7 @@ function track(...paths: string[]): void {
test.describe('Standalone terminal window β€” live Electron', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'Desktop is darwin-only.');
- test.skip(!BUILD_EXISTS, `Main build missing at ${MAIN_ENTRY} β€” run "bun run build:desktop".`);
+ test.skip(!TARGET.exists, TARGET.missingReason);
test.skip(
IS_CI,
'Quarantined on CI: constrained-runner degradation on the live-Electron terminal surface, same class as terminal-dock (inkeep/agents-private#2187). Runs in local dev.',
diff --git a/packages/desktop/tests/smoke/theme-sync.e2e.ts b/packages/desktop/tests/smoke/theme-sync.e2e.ts
index a1e4ad9a1..e2c4a8f15 100644
--- a/packages/desktop/tests/smoke/theme-sync.e2e.ts
+++ b/packages/desktop/tests/smoke/theme-sync.e2e.ts
@@ -30,27 +30,25 @@
* Skip conditions match the existing `deep-link.e2e.ts` / `external-
* link.e2e.ts` pattern:
* - `OK_DESKTOP_E2E_SMOKE !== '1'` β€” opt-in gate so unrelated
- * `bunx playwright test` runs don't try to launch Electron.
+ * `pnpm exec playwright test` runs don't try to launch Electron.
* - `process.platform !== 'darwin'` β€” driver uses macOS `open(1)` to
* fire the deep link, and the chrome stack is darwin-only in v0.
- * - `out/main/index.js` missing β€” needs a prior `bun run build:desktop`.
+ * - `out/main/index.js` missing β€” needs a prior `pnpm run build:desktop`.
*/
import { execSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
-import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import { _electron as electron } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
// `--user-data-dir` is the only reliable way to redirect Electron's
// `app.getPath('userData')` on macOS β€” `HOME`/`USERPROFILE` env vars don't
@@ -66,10 +64,7 @@ function userDataDirFor(home: string): string {
test.describe('chrome-modernization theme-sync smoke', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'Driver uses macOS open(1) and chrome stack is darwin-only in v0.');
- test.skip(
- !BUILD_EXISTS,
- `Main build missing at ${MAIN_ENTRY} β€” run "bun run build:desktop" first.`,
- );
+ test.skip(!TARGET.exists, TARGET.missingReason);
test('cold-launch chrome correct + setThemeSource roundtrips through main', async ({
captureStderrFor,
@@ -90,10 +85,13 @@ test.describe('chrome-modernization theme-sync smoke', () => {
'# Theme Sync Smoke\n\nFixture for cold-launch chrome verification.\n',
);
- const app = await electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${userDataDirFor(projectDir)}`],
- timeout: 30_000,
- });
+ const app = await electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${userDataDirFor(projectDir)}`],
+ timeout: 30_000,
+ }),
+ );
captureStderrFor(app, { cleanupDirs: [projectDir] });
// Wait for first window (Navigator on cold launch). Confirms whenReady
@@ -211,10 +209,13 @@ test.describe('chrome-modernization theme-sync smoke', () => {
'# Theme Sync Rapid\n\nFixture for rapid theme change + IPC rejection.\n',
);
- const app = await electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${userDataDirFor(projectDir)}`],
- timeout: 30_000,
- });
+ const app = await electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${userDataDirFor(projectDir)}`],
+ timeout: 30_000,
+ }),
+ );
captureStderrFor(app, { cleanupDirs: [projectDir] });
await app.firstWindow({ timeout: 15_000 });
@@ -410,10 +411,13 @@ test.describe('chrome-modernization theme-sync smoke', () => {
'# Theme Sync RT\n\nFixture for prefers-reduced-transparency propagation.\n',
);
- const app = await electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${userDataDirFor(projectDir)}`],
- timeout: 30_000,
- });
+ const app = await electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${userDataDirFor(projectDir)}`],
+ timeout: 30_000,
+ }),
+ );
captureStderrFor(app, { cleanupDirs: [projectDir] });
await app.firstWindow({ timeout: 15_000 });
diff --git a/packages/desktop/tests/smoke/uninstall-ipc-bridge.e2e.ts b/packages/desktop/tests/smoke/uninstall-ipc-bridge.e2e.ts
index 0bf491934..45973d53f 100644
--- a/packages/desktop/tests/smoke/uninstall-ipc-bridge.e2e.ts
+++ b/packages/desktop/tests/smoke/uninstall-ipc-bridge.e2e.ts
@@ -15,19 +15,17 @@
* darwin only, and a prior `pnpm run build:desktop`.
*/
-import { existsSync, mkdtempSync } from 'node:fs';
+import { mkdtempSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import { _electron as electron, type Page } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
/** What main registers for `OK_UNINSTALL_UI_PREVIEW=renderer`. */
const CONFIRM_NOTICE_TITLE = 'Uninstall OpenKnowledge?';
@@ -54,19 +52,22 @@ async function findWindowByPath(
test.describe('uninstall renderer IPC bridge smoke', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'The uninstall flow is darwin-only.');
- test.skip(!BUILD_EXISTS, `Main build missing at ${MAIN_ENTRY} β€” run "pnpm run build:desktop".`);
+ test.skip(!TARGET.exists, TARGET.missingReason);
test('carries main’s screen down and the user’s intent back up', async ({ captureStderrFor }) => {
const home = mkdtempSync(join(tmpdir(), 'ok-uninstall-ipc-'));
- const app = await electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${join(home, 'electron-userdata')}`],
- // `renderer` opens the React uninstall window showing the confirm notice
- // and closes it on the first intent. Nothing is removed; gated on
- // `!app.isPackaged` in main.
- env: { ...process.env, OK_UNINSTALL_UI_PREVIEW: 'renderer' },
- timeout: 30_000,
- });
+ const app = await electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${join(home, 'electron-userdata')}`],
+ // `renderer` opens the React uninstall window showing the confirm notice
+ // and closes it on the first intent. Nothing is removed; gated on
+ // `!app.isPackaged` in main.
+ env: { ...process.env, OK_UNINSTALL_UI_PREVIEW: 'renderer' },
+ timeout: 30_000,
+ }),
+ );
captureStderrFor(app, { cleanupDirs: [home] });
// Both windows are located by path, never by open order: the preview opens
diff --git a/packages/desktop/tests/smoke/uninstall-notice.e2e.ts b/packages/desktop/tests/smoke/uninstall-notice.e2e.ts
index b695c55af..42837125f 100644
--- a/packages/desktop/tests/smoke/uninstall-notice.e2e.ts
+++ b/packages/desktop/tests/smoke/uninstall-notice.e2e.ts
@@ -13,19 +13,17 @@
* darwin only, and a prior `pnpm run build:desktop`.
*/
-import { existsSync, mkdtempSync } from 'node:fs';
+import { mkdtempSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import { _electron as electron, type Page } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
const CONFIRM_HEADING = 'Uninstall OpenKnowledge?';
const COMPLETION_HEADING = 'OpenKnowledge files were removed';
@@ -65,21 +63,24 @@ async function launchNoticePreview(
prefix: string,
): Promise<{ app: import('@playwright/test').ElectronApplication; home: string }> {
const home = mkdtempSync(join(tmpdir(), prefix));
- const app = await electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${join(home, 'electron-userdata')}`],
- // `notice` shows the confirm question and the completion recap back to
- // back, then reports how main resolved each. Nothing is removed, nothing is
- // revealed in Finder; gated on `!app.isPackaged` in main.
- env: { ...process.env, OK_UNINSTALL_UI_PREVIEW: 'notice' },
- timeout: 30_000,
- });
+ const app = await electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${join(home, 'electron-userdata')}`],
+ // `notice` shows the confirm question and the completion recap back to
+ // back, then reports how main resolved each. Nothing is removed, nothing is
+ // revealed in Finder; gated on `!app.isPackaged` in main.
+ env: { ...process.env, OK_UNINSTALL_UI_PREVIEW: 'notice' },
+ timeout: 30_000,
+ }),
+ );
return { app, home };
}
test.describe('uninstall notice smoke', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'The uninstall flow is darwin-only.');
- test.skip(!BUILD_EXISTS, `Main build missing at ${MAIN_ENTRY} β€” run "pnpm run build:desktop".`);
+ test.skip(!TARGET.exists, TARGET.missingReason);
test('pressing each notice through carries the answer to main', async ({ captureStderrFor }) => {
const { app, home } = await launchNoticePreview('ok-uninstall-notice-');
diff --git a/packages/desktop/tests/smoke/uninstall-picker.e2e.ts b/packages/desktop/tests/smoke/uninstall-picker.e2e.ts
index 16e87c1d3..a0df91bfa 100644
--- a/packages/desktop/tests/smoke/uninstall-picker.e2e.ts
+++ b/packages/desktop/tests/smoke/uninstall-picker.e2e.ts
@@ -12,19 +12,17 @@
* darwin only, and a prior `pnpm run build:desktop`.
*/
-import { existsSync, mkdtempSync } from 'node:fs';
+import { mkdtempSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import { _electron as electron, type Page } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
/** The stand-in projects `OK_UNINSTALL_UI_PREVIEW=picker` offers, home-relative. */
const PREVIEW_PROJECTS = ['/Notes', '/Work/Team Handbook', '/Personal/Journal'];
@@ -51,21 +49,24 @@ async function findWindowByPath(
test.describe('uninstall project picker smoke', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'The uninstall flow is darwin-only.');
- test.skip(!BUILD_EXISTS, `Main build missing at ${MAIN_ENTRY} β€” run "pnpm run build:desktop".`);
+ test.skip(!TARGET.exists, TARGET.missingReason);
test('renders main’s projects and carries a confirmed selection back', async ({
captureStderrFor,
}) => {
const home = mkdtempSync(join(tmpdir(), 'ok-uninstall-picker-'));
- const app = await electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${join(home, 'electron-userdata')}`],
- // `picker` opens only the project picker, over stand-in candidates, and
- // resolves without entering the flow. Nothing is removed; gated on
- // `!app.isPackaged` in main.
- env: { ...process.env, OK_UNINSTALL_UI_PREVIEW: 'picker' },
- timeout: 30_000,
- });
+ const app = await electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${join(home, 'electron-userdata')}`],
+ // `picker` opens only the project picker, over stand-in candidates, and
+ // resolves without entering the flow. Nothing is removed; gated on
+ // `!app.isPackaged` in main.
+ env: { ...process.env, OK_UNINSTALL_UI_PREVIEW: 'picker' },
+ timeout: 30_000,
+ }),
+ );
captureStderrFor(app, { cleanupDirs: [home] });
await app.firstWindow({ timeout: 20_000 });
@@ -119,11 +120,14 @@ test.describe('uninstall project picker smoke', () => {
test('closing the picker window cancels rather than proceeding', async ({ captureStderrFor }) => {
const home = mkdtempSync(join(tmpdir(), 'ok-uninstall-picker-close-'));
- const app = await electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${join(home, 'electron-userdata')}`],
- env: { ...process.env, OK_UNINSTALL_UI_PREVIEW: 'picker' },
- timeout: 30_000,
- });
+ const app = await electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${join(home, 'electron-userdata')}`],
+ env: { ...process.env, OK_UNINSTALL_UI_PREVIEW: 'picker' },
+ timeout: 30_000,
+ }),
+ );
captureStderrFor(app, { cleanupDirs: [home] });
await app.firstWindow({ timeout: 20_000 });
diff --git a/packages/desktop/tests/smoke/uninstall-survey.e2e.ts b/packages/desktop/tests/smoke/uninstall-survey.e2e.ts
index 80b8e908e..af638a511 100644
--- a/packages/desktop/tests/smoke/uninstall-survey.e2e.ts
+++ b/packages/desktop/tests/smoke/uninstall-survey.e2e.ts
@@ -13,19 +13,17 @@
* darwin only, and a prior `pnpm run build:desktop`.
*/
-import { existsSync, mkdtempSync } from 'node:fs';
+import { mkdtempSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import { _electron as electron, type Page } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
async function findWindowByPath(
app: import('@playwright/test').ElectronApplication,
@@ -50,21 +48,24 @@ async function launchSurveyPreview(
prefix: string,
): Promise<{ app: import('@playwright/test').ElectronApplication; home: string }> {
const home = mkdtempSync(join(tmpdir(), prefix));
- const app = await electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${join(home, 'electron-userdata')}`],
- // `survey` opens only the churn survey and echoes what main resolved back
- // onto a notice. Nothing is removed and nothing is POSTed; gated on
- // `!app.isPackaged` in main.
- env: { ...process.env, OK_UNINSTALL_UI_PREVIEW: 'survey' },
- timeout: 30_000,
- });
+ const app = await electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${join(home, 'electron-userdata')}`],
+ // `survey` opens only the churn survey and echoes what main resolved back
+ // onto a notice. Nothing is removed and nothing is POSTed; gated on
+ // `!app.isPackaged` in main.
+ env: { ...process.env, OK_UNINSTALL_UI_PREVIEW: 'survey' },
+ timeout: 30_000,
+ }),
+ );
return { app, home };
}
test.describe('uninstall churn survey smoke', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'The uninstall flow is darwin-only.');
- test.skip(!BUILD_EXISTS, `Main build missing at ${MAIN_ENTRY} β€” run "pnpm run build:desktop".`);
+ test.skip(!TARGET.exists, TARGET.missingReason);
test('carries a filled-in survey back to main as answers', async ({ captureStderrFor }) => {
const { app, home } = await launchSurveyPreview('ok-uninstall-survey-');
diff --git a/packages/desktop/tests/smoke/uninstall-window-chrome.e2e.ts b/packages/desktop/tests/smoke/uninstall-window-chrome.e2e.ts
index 5621db0e2..7d32de047 100644
--- a/packages/desktop/tests/smoke/uninstall-window-chrome.e2e.ts
+++ b/packages/desktop/tests/smoke/uninstall-window-chrome.e2e.ts
@@ -26,19 +26,17 @@
* darwin only, and a prior `pnpm run build:desktop`.
*/
-import { existsSync, mkdtempSync } from 'node:fs';
+import { mkdtempSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import { _electron as electron, type Page } from '@playwright/test';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
/** The family `packages/app` loads via `@fontsource-variable/inter`. */
const APP_FONT_FAMILY = 'Inter Variable';
@@ -65,20 +63,23 @@ async function findWindowByPath(
test.describe('uninstall renderer chrome smoke', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'The uninstall flow is darwin-only.');
- test.skip(!BUILD_EXISTS, `Main build missing at ${MAIN_ENTRY} β€” run "pnpm run build:desktop".`);
+ test.skip(!TARGET.exists, TARGET.missingReason);
test('loads the app font, the app tokens, and the theme main resolved', async ({
captureStderrFor,
}) => {
const home = mkdtempSync(join(tmpdir(), 'ok-uninstall-chrome-'));
- const app = await electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${join(home, 'electron-userdata')}`],
- // `renderer` opens the React uninstall window on its own β€” no picker, no
- // cleanup, nothing removed. Gated on `!app.isPackaged` in main.
- env: { ...process.env, OK_UNINSTALL_UI_PREVIEW: 'renderer' },
- timeout: 30_000,
- });
+ const app = await electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${join(home, 'electron-userdata')}`],
+ // `renderer` opens the React uninstall window on its own β€” no picker, no
+ // cleanup, nothing removed. Gated on `!app.isPackaged` in main.
+ env: { ...process.env, OK_UNINSTALL_UI_PREVIEW: 'renderer' },
+ timeout: 30_000,
+ }),
+ );
captureStderrFor(app, { cleanupDirs: [home] });
// Cold launch opens Navigator from `index.html`; the preview opens the
diff --git a/packages/desktop/tests/smoke/window-min-size.e2e.ts b/packages/desktop/tests/smoke/window-min-size.e2e.ts
index be9752710..2b675a2eb 100644
--- a/packages/desktop/tests/smoke/window-min-size.e2e.ts
+++ b/packages/desktop/tests/smoke/window-min-size.e2e.ts
@@ -18,24 +18,22 @@
* Skip gates (same as the rest of the smoke suite):
* - `OK_DESKTOP_E2E_SMOKE !== '1'` β€” opt-in.
* - `process.platform !== 'darwin'` β€” darwin-only.
- * - `out/main/index.js` missing β€” `bun run build:desktop` must have run.
+ * - `out/main/index.js` missing β€” `pnpm run build:desktop` must have run.
*/
-import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
import type { ElectronApplication, JSHandle, Page } from '@playwright/test';
import { _electron as electron } from '@playwright/test';
import { WINDOW_MIN_SIZE } from '../../src/main/window-min-size.ts';
+import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';
import { expect, test } from './_helpers/smoke-test';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const TARGET = resolveDesktopTarget();
const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
const DARWIN = process.platform === 'darwin';
-const BUILD_EXISTS = existsSync(MAIN_ENTRY);
interface SeededHome {
tmpHome: string;
@@ -78,15 +76,18 @@ function seedHomeWithLastOpenedProject(prefix: string): SeededHome {
}
async function launchApp(tmpHome: string): Promise<ElectronApplication> {
- return electron.launch({
- args: [MAIN_ENTRY, `--user-data-dir=${userDataDirFor(tmpHome)}`],
- timeout: 30_000,
- env: {
- ...process.env,
- HOME: tmpHome,
- OK_DESKTOP_E2E_SMOKE: '1',
- },
- });
+ return electron.launch(
+ desktopLaunchOptions({
+ target: TARGET,
+ args: [`--user-data-dir=${userDataDirFor(tmpHome)}`],
+ timeout: 30_000,
+ env: {
+ ...process.env,
+ HOME: tmpHome,
+ OK_DESKTOP_E2E_SMOKE: '1',
+ },
+ }),
+ );
}
async function findWindow(
@@ -137,10 +138,7 @@ async function readMinSizeFor(app: ElectronApplication, page: Page): Promise<Min
test.describe('BrowserWindow min-size smoke', () => {
test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
test.skip(!DARWIN, 'Smoke harness is darwin-only in v0.');
- test.skip(
- !BUILD_EXISTS,
- `Main build missing at ${MAIN_ENTRY} β€” run "bun run build:desktop" first.`,
- );
+ test.skip(!TARGET.exists, TARGET.missingReason);
test(`Editor window enforces ${WINDOW_MIN_SIZE.EDITOR.width}x${WINDOW_MIN_SIZE.EDITOR.height} min; Navigator window enforces ${WINDOW_MIN_SIZE.NAVIGATOR.width}x${WINDOW_MIN_SIZE.NAVIGATOR.height} min`, async ({
captureStderrFor,
diff --git a/packages/desktop/tests/unit/playwright-packaged-config.test.ts b/packages/desktop/tests/unit/playwright-packaged-config.test.ts
new file mode 100644
index 000000000..28bc83b0f
--- /dev/null
+++ b/packages/desktop/tests/unit/playwright-packaged-config.test.ts
@@ -0,0 +1,58 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import packagedConfig, {
+ PACKAGED_JSON_REPORT_PATH,
+ PACKAGED_SMOKE_SUBSET,
+} from '../../playwright.packaged.config';
+
+const DESKTOP_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const unpackagedSource = readFileSync(join(DESKTOP_ROOT, 'playwright.config.ts'), 'utf8');
+
+describe('playwright.packaged.config', () => {
+ it('selects exactly the FR5a subset', () => {
+ // Pinning the literal list is the point: silently widening the packaged
+ // tier makes release gating slower and flakier, and silently narrowing it
+ // makes the gate weaker than the spec says it is. Either direction should
+ // require editing this assertion on purpose.
+ expect([...PACKAGED_SMOKE_SUBSET]).toEqual([
+ 'consent-dialog.e2e.ts',
+ 'create-new-project.e2e.ts',
+ 'mcp-wiring.e2e.ts',
+ ]);
+ expect(packagedConfig.testMatch).toEqual([
+ '**/consent-dialog.e2e.ts',
+ '**/create-new-project.e2e.ts',
+ '**/mcp-wiring.e2e.ts',
+ ]);
+ });
+
+ it('runs the same test directory as the unpackaged tier', () => {
+ expect(packagedConfig.testDir).toBe('./tests/smoke');
+ });
+
+ it('omits the stale-build guard, which cannot describe a packaged bundle', () => {
+ expect(packagedConfig.globalSetup).toBeUndefined();
+ // Sanity: the unpackaged tier still has it, so this is a deliberate
+ // difference rather than the guard having been dropped everywhere.
+ expect(unpackagedSource).toContain('stale-build-guard');
+ });
+
+ it('writes its JSON report to a path the unpackaged tier does not use', () => {
+ expect(PACKAGED_JSON_REPORT_PATH).not.toBe('test-results/desktop-smoke-results.json');
+ expect(unpackagedSource).not.toContain(PACKAGED_JSON_REPORT_PATH);
+ const json = (packagedConfig.reporter as [string, Record<string, unknown>][]).find(
+ ([name]) => name === 'json',
+ );
+ expect(json?.[1]?.outputFile).toBe(PACKAGED_JSON_REPORT_PATH);
+ });
+
+ it('leaves the required desktop-smoke check untouched', () => {
+ // A `projects` array on the unpackaged config would change
+ // testInfo.project.retries, which electron-stderr.ts reads. The packaged
+ // tier exists as its own file precisely to avoid that.
+ expect(unpackagedSource).not.toMatch(/^\s*projects:/m);
+ expect(packagedConfig.projects).toBeUndefined();
+ });
+});