Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Build shipped OK artifacts without the Turbo cache (#5226)

Nick Gomez1c27c9871bcb
diff --git a/.github/scripts/assert-native-set.mjs b/.github/scripts/assert-native-set.mjs
new file mode 100644
index 000000000..2ff1712f6
--- /dev/null
+++ b/.github/scripts/assert-native-set.mjs
@@ -0,0 +1,242 @@
+import { createHash } from 'node:crypto';
+import { appendFileSync, readdirSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+
+export const NATIVE_CONFIG_DIR = 'packages/native-config';
+export const CLI_NATIVE_DIR = 'packages/cli/dist/native';
+export const PLATFORMS = { mac: 'darwin', windows: 'win32', linux: 'linux' };
+export const RECOVERY_SECTION = 'Native addon staging';
+
+const PLATFORM_NAMES = Object.keys(PLATFORMS);
+
+export function parsePlatforms(list) {
+ if (typeof list !== 'string' || list === '') {
+ throw new Error(
+ `platforms needs a comma-separated list of ${PLATFORM_NAMES.join(', ')}, or none`,
+ );
+ }
+ if (list === 'none') return [];
+ const names = [...new Set(list.split(',').map((name) => name.trim()))];
+ const unknown = names.filter((name) => !Object.hasOwn(PLATFORMS, name));
+ if (unknown.length > 0) {
+ throw new Error(
+ `unknown platform ${unknown.join(', ')}; the platforms are ${PLATFORM_NAMES.join(', ')}`,
+ );
+ }
+ return names;
+}
+
+function declaredTargets(napi, parseTriple) {
+ const { binaryName, targets } = napi ?? {};
+ if (typeof binaryName !== 'string' || !Array.isArray(targets) || targets.length === 0) {
+ throw new Error(`${NATIVE_CONFIG_DIR}/package.json declares no napi binaryName and targets`);
+ }
+ return targets.map((target) => {
+ const { platform, arch, platformArchABI } = parseTriple(target);
+ const owner = PLATFORM_NAMES.find((name) => PLATFORMS[name] === platform);
+ if (!owner) {
+ throw new Error(
+ `napi target ${target} is for ${platform}, which no release platform (${PLATFORM_NAMES.join(', ')}) packages`,
+ );
+ }
+ return { platform: owner, os: platform, arch, name: `${binaryName}.${platformArchABI}.node` };
+ });
+}
+
+export function expectedBinaries({ napi, parseTriple, mode, platforms = [], host = process }) {
+ if (mode !== 'host' && mode !== 'platforms') {
+ throw new Error(`mode must be one of host, platforms, not ${mode}`);
+ }
+ const declared = declaredTargets(napi, parseTriple);
+ const bare =
+ mode === 'platforms'
+ ? platforms.filter((name) => !declared.some(({ platform }) => platform === name))
+ : [];
+ if (bare.length > 0) {
+ throw new Error(
+ `no declared napi target in ${NATIVE_CONFIG_DIR}/package.json is for ${bare.join(', ')}`,
+ );
+ }
+ const chosen =
+ mode === 'platforms'
+ ? declared.filter(({ platform }) => platforms.includes(platform))
+ : declared.filter(({ os, arch }) => os === host.platform && arch === host.arch);
+ if (mode === 'host' && chosen.length !== 1) {
+ throw new Error(
+ `host mode needs exactly one declared napi target for ${host.platform}-${host.arch}; found ${chosen.length}`,
+ );
+ }
+ return chosen.map(({ name }) => name).sort();
+}
+
+function readNapi(root) {
+ return JSON.parse(readFileSync(join(root, NATIVE_CONFIG_DIR, 'package.json'), 'utf8')).napi;
+}
+
+function inventory(root, dir) {
+ const files = readdirSync(join(root, dir)).filter((name) => name.endsWith('.node'));
+ return new Map(
+ files.sort().map((name) => {
+ const bytes = readFileSync(join(root, dir, name));
+ return [
+ name,
+ { size: bytes.length, sha256: createHash('sha256').update(bytes).digest('hex') },
+ ];
+ }),
+ );
+}
+
+export function assertNativeSet({ root, mode, platforms = [], parseTriple, host = process }) {
+ const lines = [];
+ const errors = [];
+ let expected;
+ let allowed;
+ try {
+ const napi = readNapi(root);
+ expected = expectedBinaries({ napi, parseTriple, mode, platforms, host });
+ allowed =
+ mode === 'host' ? expected : declaredTargets(napi, parseTriple).map(({ name }) => name);
+ } catch (error) {
+ return { lines, errors: [`cannot derive the expected native set: ${error.message}`] };
+ }
+ const stray = mode === 'host' ? 'is not a declared host target' : 'is not a declared napi target';
+ const sets = new Map();
+ for (const dir of [NATIVE_CONFIG_DIR, CLI_NATIVE_DIR]) {
+ try {
+ sets.set(dir, inventory(root, dir));
+ } catch (error) {
+ errors.push(`cannot read ${dir}: ${error.message}`);
+ continue;
+ }
+ const found = sets.get(dir);
+ for (const [name, { size, sha256 }] of found)
+ lines.push(`native-set ${dir}/${name} ${size} ${sha256}`);
+ for (const name of expected.filter((name) => !found.has(name)))
+ errors.push(`${dir}/${name} is missing`);
+ for (const name of [...found.keys()].filter((name) => !allowed.includes(name)))
+ errors.push(`${dir}/${name} ${stray}`);
+ for (const name of expected.filter((name) => found.get(name)?.size === 0))
+ errors.push(`${dir}/${name} is empty`);
+ }
+ const source = sets.get(NATIVE_CONFIG_DIR);
+ const shipped = sets.get(CLI_NATIVE_DIR);
+ if (source && shipped) {
+ for (const [name, { sha256 }] of shipped) {
+ if (source.has(name) && source.get(name).sha256 !== sha256) {
+ errors.push(`${CLI_NATIVE_DIR}/${name} differs from ${NATIVE_CONFIG_DIR}/${name}`);
+ }
+ }
+ }
+ return { lines, errors, expected };
+}
+
+export function stagingVerdict({ root, serves, requires, parseTriple }) {
+ const napi = readNapi(root);
+ const staged = inventory(root, NATIVE_CONFIG_DIR);
+ const judged = new Map(
+ [...new Set([...serves, ...requires])].map((platform) => [
+ platform,
+ expectedBinaries({ napi, parseTriple, mode: 'platforms', platforms: [platform] }),
+ ]),
+ );
+ const packaged = [];
+ const refusals = [];
+ const drops = [];
+ for (const platform of serves) {
+ const missing = judged.get(platform).filter((name) => !(staged.get(name)?.size > 0));
+ if (missing.length === 0) packaged.push(platform);
+ else if (requires.includes(platform)) refusals.push({ platform, missing });
+ else drops.push({ platform, missing });
+ }
+ return { packaged: refusals.length > 0 ? [] : packaged, refusals, drops };
+}
+
+async function loadParseTriple(root) {
+ const requireFromNativeConfig = createRequire(join(root, NATIVE_CONFIG_DIR, 'package.json'));
+ const { parseTriple } = await import(
+ pathToFileURL(requireFromNativeConfig.resolve('@napi-rs/cli')).href
+ );
+ if (typeof parseTriple !== 'function') throw new Error('@napi-rs/cli exports no parseTriple');
+ return parseTriple;
+}
+
+function judgeStaging(args, root, parseTriple) {
+ const { values } = parseArgs({
+ args,
+ options: {
+ serves: { type: 'string' },
+ requires: { type: 'string' },
+ reason: { type: 'string', default: '' },
+ recovery: { type: 'string', default: '' },
+ },
+ });
+ const serves = parsePlatforms(values.serves);
+ const requires = parsePlatforms(values.requires);
+ const { packaged, refusals, drops } = stagingVerdict({ root, serves, requires, parseTriple });
+ const why = values.reason ? ` (${values.reason})` : '';
+ for (const { platform, missing } of drops) {
+ console.log(
+ `::warning::DEGRADED CUT: ${platform} is not a required platform, and its staged native-config set is missing ${missing.join(', ')}${why}, so ${platform} is not packaged or shipped this cut. Its clients 404 this cut's channel manifest and stay on their current version.`,
+ );
+ if (process.env.GITHUB_STEP_SUMMARY) {
+ appendFileSync(
+ process.env.GITHUB_STEP_SUMMARY,
+ `### ⚠️ Degraded cut: ${platform} not packaged (staged native-config set is missing ${missing.join(', ')})\n`,
+ );
+ }
+ }
+ for (const { platform, missing } of refusals) {
+ console.log(
+ `::error::native-set: ${platform} is a required platform, and its staged native-config set is missing ${missing.join(', ')}${why}. ${values.recovery}`.trimEnd(),
+ );
+ }
+ if (refusals.length > 0) return 1;
+ const list = packaged.length > 0 ? packaged.join(',') : 'none';
+ if (process.env.GITHUB_OUTPUT) appendFileSync(process.env.GITHUB_OUTPUT, `platforms=${list}\n`);
+ console.log(`native-set staged: packaging ${list}`);
+ return 0;
+}
+
+export async function main(argv = process.argv.slice(2), root = process.cwd()) {
+ const [mode, ...rest] = argv;
+ let parseTriple;
+ try {
+ parseTriple = await loadParseTriple(root);
+ } catch (error) {
+ console.log(
+ `::error::cannot load napi's target parser from ${NATIVE_CONFIG_DIR}: ${error.message}`,
+ );
+ return 1;
+ }
+ try {
+ if (mode === 'staged') return judgeStaging(rest, root, parseTriple);
+ if (mode !== 'host' && mode !== 'platforms') {
+ throw new Error(`mode must be one of host, platforms, staged, not ${mode}`);
+ }
+ const platforms = mode === 'platforms' ? parsePlatforms(rest[0]) : [];
+ const label = mode === 'host' ? 'host' : platforms.join(', ') || 'no platform';
+ const { lines, errors, expected } = assertNativeSet({ root, mode, platforms, parseTriple });
+ for (const line of lines) console.log(line);
+ if (errors.length > 0) {
+ for (const error of errors) console.log(`::error::native-set: ${error}`);
+ console.log(
+ `::error::native-set: the built binaries are not the declared set for ${label}. If a staged binary is missing, re-run native-config-prebuild.yml on an ancestor of this commit, then resume per RELEASES.md '${RECOVERY_SECTION}'.`,
+ );
+ return 1;
+ }
+ console.log(
+ `native-set ok: ${expected.length} binaries for ${label} present, non-empty and identical in ${NATIVE_CONFIG_DIR} and ${CLI_NATIVE_DIR}`,
+ );
+ return 0;
+ } catch (error) {
+ console.log(`::error::native-set: ${error.message}`);
+ return 1;
+ }
+}
+
+if (import.meta.main) {
+ process.exitCode = await main();
+}
diff --git a/.github/scripts/assert-native-set.test.mjs b/.github/scripts/assert-native-set.test.mjs
new file mode 100644
index 000000000..706525584
--- /dev/null
+++ b/.github/scripts/assert-native-set.test.mjs
@@ -0,0 +1,512 @@
+import { spawnSync } from 'node:child_process';
+import {
+ copyFileSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ rmSync,
+ symlinkSync,
+ truncateSync,
+ writeFileSync,
+} from 'node:fs';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { afterEach, describe, expect, test } from 'vitest';
+import {
+ assertNativeSet,
+ CLI_NATIVE_DIR,
+ expectedBinaries,
+ NATIVE_CONFIG_DIR,
+ parsePlatforms,
+ RECOVERY_SECTION,
+ stagingVerdict,
+} from './assert-native-set.mjs';
+
+const OK_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const SCRIPT = fileURLToPath(new URL('./assert-native-set.mjs', import.meta.url));
+const REAL_NATIVE_CONFIG = join(OK_ROOT, NATIVE_CONFIG_DIR);
+const napi = JSON.parse(readFileSync(join(REAL_NATIVE_CONFIG, 'package.json'), 'utf8')).napi;
+const requireFromNativeConfig = createRequire(join(REAL_NATIVE_CONFIG, 'package.json'));
+const { parseTriple } = await import(
+ pathToFileURL(requireFromNativeConfig.resolve('@napi-rs/cli')).href
+);
+const EVERY_PLATFORM = ['mac', 'windows', 'linux'];
+const DARWIN_ARM64 = { platform: 'darwin', arch: 'arm64' };
+const expected = (platforms) =>
+ expectedBinaries({ napi, parseTriple, mode: 'platforms', platforms });
+const ALL = expected(EVERY_PLATFORM);
+const WINDOWS = expected(['windows']);
+const LINUX = expected(['linux']);
+const RUNNER = `${process.platform}-${process.arch}`;
+const SINGLE_TARGET_RUNNERS = {
+ 'darwin-arm64': 'native-config.darwin-arm64.node',
+ 'darwin-x64': 'native-config.darwin-x64.node',
+ 'win32-arm64': 'native-config.win32-arm64-msvc.node',
+ 'win32-x64': 'native-config.win32-x64-msvc.node',
+};
+const RUNNER_BINARY = SINGLE_TARGET_RUNNERS[RUNNER];
+
+const scratches = [];
+
+afterEach(() => {
+ for (const dir of scratches.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+function scratch(prefix) {
+ const dir = mkdtempSync(join(tmpdir(), prefix));
+ scratches.push(dir);
+ return dir;
+}
+
+function tree(binaries, { declared = napi, shipped = binaries } = {}) {
+ const root = scratch('ok-native-set-');
+ mkdirSync(join(root, NATIVE_CONFIG_DIR), { recursive: true });
+ mkdirSync(join(root, CLI_NATIVE_DIR), { recursive: true });
+ writeFileSync(join(root, NATIVE_CONFIG_DIR, 'package.json'), JSON.stringify({ napi: declared }));
+ for (const name of binaries)
+ writeFileSync(join(root, NATIVE_CONFIG_DIR, name), `bytes of ${name}`);
+ for (const name of shipped)
+ copyFileSync(join(root, NATIVE_CONFIG_DIR, name), join(root, CLI_NATIVE_DIR, name));
+ return root;
+}
+
+const without = (names, ...dropped) => names.filter((name) => !dropped.includes(name));
+const undeclaring = (os) => ({
+ ...napi,
+ targets: napi.targets.filter((target) => parseTriple(target).platform !== os),
+});
+const NO_WINDOWS_TARGET = `no declared napi target in ${NATIVE_CONFIG_DIR}/package.json is for windows`;
+
+const check = (root, platforms = EVERY_PLATFORM) =>
+ assertNativeSet({ root, mode: 'platforms', platforms, parseTriple });
+const checkHost = (root, host = DARWIN_ARM64) =>
+ assertNativeSet({ root, mode: 'host', parseTriple, host });
+const verdict = (root, { serves, requires }) =>
+ stagingVerdict({ root, serves, requires, parseTriple });
+
+describe('the expected set comes from native-config’s declared napi targets', () => {
+ test('every platform’s declared targets, named the way napi names them', () => {
+ expect(ALL).toEqual([
+ 'native-config.darwin-arm64.node',
+ 'native-config.darwin-x64.node',
+ 'native-config.linux-arm64-gnu.node',
+ 'native-config.linux-arm64-musl.node',
+ 'native-config.linux-x64-gnu.node',
+ 'native-config.linux-x64-musl.node',
+ 'native-config.win32-arm64-msvc.node',
+ 'native-config.win32-x64-msvc.node',
+ ]);
+ });
+
+ test('each release platform owns the declared targets of its operating system', () => {
+ expect(expected(['mac'])).toEqual([
+ 'native-config.darwin-arm64.node',
+ 'native-config.darwin-x64.node',
+ ]);
+ expect(WINDOWS).toEqual([
+ 'native-config.win32-arm64-msvc.node',
+ 'native-config.win32-x64-msvc.node',
+ ]);
+ expect(LINUX).toEqual([
+ 'native-config.linux-arm64-gnu.node',
+ 'native-config.linux-arm64-musl.node',
+ 'native-config.linux-x64-gnu.node',
+ 'native-config.linux-x64-musl.node',
+ ]);
+ });
+
+ test('host mode keeps the one declared target this runner builds', () => {
+ expect(expectedBinaries({ napi, parseTriple, mode: 'host', host: DARWIN_ARM64 })).toEqual([
+ 'native-config.darwin-arm64.node',
+ ]);
+ });
+
+ test('host mode refuses a runner that two declared targets match, as gnu and musl do on Linux', () => {
+ expect(() =>
+ expectedBinaries({
+ napi,
+ parseTriple,
+ mode: 'host',
+ host: { platform: 'linux', arch: 'x64' },
+ }),
+ ).toThrow('host mode needs exactly one declared napi target for linux-x64; found 2');
+ });
+
+ test('a newly declared target joins its platform’s set without editing any workflow', () => {
+ const declared = { ...napi, targets: [...napi.targets, 'riscv64gc-unknown-linux-gnu'] };
+ const { errors } = check(tree(ALL, { declared }), ['linux']);
+ expect(errors).toEqual([
+ `${NATIVE_CONFIG_DIR}/native-config.linux-riscv64-gnu.node is missing`,
+ `${CLI_NATIVE_DIR}/native-config.linux-riscv64-gnu.node is missing`,
+ ]);
+ });
+
+ test('a declared target for an operating system no release platform packages is refused', () => {
+ const declared = { ...napi, targets: [...napi.targets, 'x86_64-unknown-freebsd'] };
+ expect(() =>
+ expectedBinaries({ napi: declared, parseTriple, mode: 'platforms', platforms: ['linux'] }),
+ ).toThrow(
+ 'napi target x86_64-unknown-freebsd is for freebsd, which no release platform (mac, windows, linux) packages',
+ );
+ });
+
+ test('a platform that owns no declared target is refused by name, not passed with zero binaries', () => {
+ expect(check(tree(LINUX, { declared: undeclaring('win32') }), ['windows', 'linux'])).toEqual({
+ lines: [],
+ errors: [`cannot derive the expected native set: ${NO_WINDOWS_TARGET}`],
+ });
+ expect(check(tree(LINUX, { declared: undeclaring('win32') }), ['linux']).errors).toEqual([]);
+ });
+
+ test('a platform list names only mac, windows and linux, and none means no platform', () => {
+ expect(parsePlatforms('windows,linux')).toEqual(['windows', 'linux']);
+ expect(parsePlatforms('none')).toEqual([]);
+ expect(() => parsePlatforms('')).toThrow('platforms needs a comma-separated list');
+ expect(() => parsePlatforms('linux,toString')).toThrow('unknown platform toString');
+ });
+});
+
+describe('the assertion', () => {
+ test('passes an exact, non-empty, identical set and prints each file’s name, size and sha256', () => {
+ const { errors, lines } = check(tree(ALL));
+ expect(errors).toEqual([]);
+ expect(lines).toHaveLength(16);
+ expect(lines[0]).toMatch(
+ /^native-set packages\/native-config\/native-config\.darwin-arm64\.node \d+ [0-9a-f]{64}$/,
+ );
+ });
+
+ test('reds when one binary is missing from what the CLI ships', () => {
+ const shipped = without(ALL, 'native-config.win32-arm64-msvc.node');
+ expect(check(tree(ALL, { shipped })).errors).toEqual([
+ `${CLI_NATIVE_DIR}/native-config.win32-arm64-msvc.node is missing`,
+ ]);
+ });
+
+ test('reds when one binary is empty', () => {
+ const root = tree(ALL);
+ truncateSync(join(root, CLI_NATIVE_DIR, 'native-config.linux-x64-gnu.node'), 0);
+ expect(check(root).errors).toEqual([
+ `${CLI_NATIVE_DIR}/native-config.linux-x64-gnu.node is empty`,
+ `${CLI_NATIVE_DIR}/native-config.linux-x64-gnu.node differs from ${NATIVE_CONFIG_DIR}/native-config.linux-x64-gnu.node`,
+ ]);
+ });
+
+ test('reds when the CLI ships different bytes of the same size than native-config holds', () => {
+ const root = tree(ALL);
+ const shipped = join(root, CLI_NATIVE_DIR, 'native-config.darwin-x64.node');
+ const original = readFileSync(shipped, 'utf8');
+ writeFileSync(shipped, `${original.slice(0, -1)}!`);
+ expect(check(root).errors).toEqual([
+ `${CLI_NATIVE_DIR}/native-config.darwin-x64.node differs from ${NATIVE_CONFIG_DIR}/native-config.darwin-x64.node`,
+ ]);
+ });
+
+ test('reds on a binary no declared target names, such as one left over in the workspace', () => {
+ const extra = [...ALL, 'native-config.leftover.node'];
+ expect(check(tree(extra)).errors).toEqual([
+ `${NATIVE_CONFIG_DIR}/native-config.leftover.node is not a declared napi target`,
+ `${CLI_NATIVE_DIR}/native-config.leftover.node is not a declared napi target`,
+ ]);
+ });
+
+ test('reds when a set cannot be read', () => {
+ const root = tree(ALL);
+ rmSync(join(root, CLI_NATIVE_DIR), { recursive: true });
+ expect(check(root).errors).toEqual([
+ expect.stringMatching(/^cannot read packages\/cli\/dist\/native: ENOENT/),
+ ]);
+ });
+
+ test('checks only the packaged platforms’ sets, and tolerates another platform’s declared binaries', () => {
+ expect(check(tree(LINUX), ['linux']).errors).toEqual([]);
+ expect(check(tree(ALL), ['linux']).errors).toEqual([]);
+ expect(
+ check(tree(without(LINUX, 'native-config.linux-arm64-musl.node')), ['linux']).errors,
+ ).toEqual([
+ `${NATIVE_CONFIG_DIR}/native-config.linux-arm64-musl.node is missing`,
+ `${CLI_NATIVE_DIR}/native-config.linux-arm64-musl.node is missing`,
+ ]);
+ });
+
+ test('host mode reds on staged binaries a host-only build must not carry', () => {
+ expect(checkHost(tree(['native-config.darwin-arm64.node'])).errors).toEqual([]);
+ expect(checkHost(tree(ALL)).errors).toHaveLength(14);
+ });
+
+ test('reds when native-config declares no targets', () => {
+ expect(check(tree(ALL, { declared: null })).errors).toEqual([
+ `cannot derive the expected native set: ${NATIVE_CONFIG_DIR}/package.json declares no napi binaryName and targets`,
+ ]);
+ });
+
+ test.skipIf(!RUNNER_BINARY)(
+ 'host mode with no host given reads this runner, which builds one declared target',
+ () => {
+ const root = tree([RUNNER_BINARY]);
+ expect(assertNativeSet({ root, mode: 'host', parseTriple }).errors).toEqual([]);
+ },
+ );
+
+ test.skipIf(process.platform !== 'linux')(
+ 'host mode with no host given refuses this Linux runner, where gnu and musl both match',
+ () => {
+ const root = tree(ALL);
+ expect(assertNativeSet({ root, mode: 'host', parseTriple }).errors).toEqual([
+ `cannot derive the expected native set: host mode needs exactly one declared napi target for ${RUNNER}; found 2`,
+ ]);
+ },
+ );
+});
+
+describe('the staging verdict', () => {
+ const staged = (names) => tree(names, { shipped: [] });
+
+ test('a gap in a required platform refuses the cut, and a complete set packages it', () => {
+ const gap = verdict(staged(without(ALL, 'native-config.win32-arm64-msvc.node')), {
+ serves: ['windows', 'linux'],
+ requires: EVERY_PLATFORM,
+ });
+ expect(gap.refusals).toEqual([
+ { platform: 'windows', missing: ['native-config.win32-arm64-msvc.node'] },
+ ]);
+ expect(gap.drops).toEqual([]);
+
+ const complete = verdict(staged(ALL), {
+ serves: ['windows', 'linux'],
+ requires: EVERY_PLATFORM,
+ });
+ expect(complete).toEqual({ packaged: ['windows', 'linux'], refusals: [], drops: [] });
+ });
+
+ test('a gap in a platform that is not required drops that platform, and the cut proceeds for the rest', () => {
+ const gap = verdict(staged(without(ALL, 'native-config.win32-x64-msvc.node')), {
+ serves: ['windows', 'linux'],
+ requires: ['mac', 'linux'],
+ });
+ expect(gap).toEqual({
+ packaged: ['linux'],
+ refusals: [],
+ drops: [{ platform: 'windows', missing: ['native-config.win32-x64-msvc.node'] }],
+ });
+
+ const complete = verdict(staged(ALL), {
+ serves: ['windows', 'linux'],
+ requires: ['mac', 'linux'],
+ });
+ expect(complete).toEqual({ packaged: ['windows', 'linux'], refusals: [], drops: [] });
+ });
+
+ test('a linux-only QA dispatch passes with the Linux set, and refuses when a Linux binary is missing', () => {
+ const linuxOnly = { serves: ['linux'], requires: ['linux'] };
+ expect(verdict(staged(LINUX), linuxOnly)).toEqual({
+ packaged: ['linux'],
+ refusals: [],
+ drops: [],
+ });
+ expect(
+ verdict(staged(without(LINUX, 'native-config.linux-arm64-gnu.node')), linuxOnly),
+ ).toEqual({
+ packaged: [],
+ refusals: [{ platform: 'linux', missing: ['native-config.linux-arm64-gnu.node'] }],
+ drops: [],
+ });
+ });
+
+ test('an empty staged binary counts as missing', () => {
+ const root = staged(LINUX);
+ truncateSync(join(root, NATIVE_CONFIG_DIR, 'native-config.linux-x64-musl.node'), 0);
+ expect(verdict(root, { serves: ['linux'], requires: ['linux'] }).refusals).toEqual([
+ { platform: 'linux', missing: ['native-config.linux-x64-musl.node'] },
+ ]);
+ });
+
+ test('a served or required platform that owns no declared target is refused by name', () => {
+ expect(() =>
+ verdict(staged(ALL), { serves: ['windows', 'linux'], requires: ['mac'] }),
+ ).not.toThrow();
+ const windowsless = tree(ALL, { declared: undeclaring('win32'), shipped: [] });
+ expect(() => verdict(windowsless, { serves: ['windows', 'linux'], requires: ['mac'] })).toThrow(
+ NO_WINDOWS_TARGET,
+ );
+ expect(() => verdict(windowsless, { serves: ['linux'], requires: ['mac', 'windows'] })).toThrow(
+ NO_WINDOWS_TARGET,
+ );
+ });
+
+ test('a zero-byte binary of a dropped platform fails neither the verdict nor the assertion of what it packaged', () => {
+ const root = tree(ALL);
+ for (const dir of [NATIVE_CONFIG_DIR, CLI_NATIVE_DIR]) {
+ truncateSync(join(root, dir, 'native-config.win32-x64-msvc.node'), 0);
+ }
+ const { packaged, refusals, drops } = verdict(root, {
+ serves: ['windows', 'linux'],
+ requires: ['mac', 'linux'],
+ });
+ expect(refusals).toEqual([]);
+ expect(drops).toEqual([
+ { platform: 'windows', missing: ['native-config.win32-x64-msvc.node'] },
+ ]);
+ expect(packaged).toEqual(['linux']);
+ expect(check(root, packaged).errors).toEqual([]);
+ expect(check(root, ['windows', 'linux']).errors).toEqual([
+ `${NATIVE_CONFIG_DIR}/native-config.win32-x64-msvc.node is empty`,
+ `${CLI_NATIVE_DIR}/native-config.win32-x64-msvc.node is empty`,
+ ]);
+ });
+
+ test('with nothing staged, required platforms refuse and the rest are dropped', () => {
+ expect(verdict(staged([]), { serves: ['windows', 'linux'], requires: ['mac'] })).toEqual({
+ packaged: [],
+ refusals: [],
+ drops: [
+ { platform: 'windows', missing: WINDOWS },
+ { platform: 'linux', missing: LINUX },
+ ],
+ });
+ expect(
+ verdict(staged([]), { serves: ['windows', 'linux'], requires: ['mac', 'windows'] }).refusals,
+ ).toEqual([{ platform: 'windows', missing: WINDOWS }]);
+ });
+});
+
+describe('as the workflow runs it', () => {
+ const withParser = (root) => {
+ symlinkSync(
+ join(REAL_NATIVE_CONFIG, 'node_modules'),
+ join(root, NATIVE_CONFIG_DIR, 'node_modules'),
+ );
+ return root;
+ };
+ const { NODE_PATH: _pnpmShimPath, ...workflowEnv } = process.env;
+ const run = (root, args, { script = SCRIPT, env = {} } = {}) =>
+ spawnSync(process.execPath, [script, ...args], {
+ cwd: root,
+ encoding: 'utf8',
+ env: { ...workflowEnv, ...env },
+ });
+ const outputs = (root) => {
+ const files = {
+ GITHUB_OUTPUT: join(root, 'output'),
+ GITHUB_STEP_SUMMARY: join(root, 'summary'),
+ };
+ for (const file of Object.values(files)) writeFileSync(file, '');
+ return files;
+ };
+ const staged = (serves, requires) => [
+ 'staged',
+ '--serves',
+ serves,
+ '--requires',
+ requires,
+ '--reason',
+ 'staged from run 1',
+ '--recovery',
+ `Re-run the prebuild, then resume per RELEASES.md '${RECOVERY_SECTION}'.`,
+ ];
+
+ test('exits 0 on the exact set and 1 with an error annotation on a missing binary', () => {
+ const exact = run(withParser(tree(ALL)), ['platforms', 'mac,windows,linux']);
+ const short = run(withParser(tree(ALL, { shipped: ALL.slice(1) })), [
+ 'platforms',
+ 'mac,windows,linux',
+ ]);
+ expect(exact.status).toBe(0);
+ expect(exact.stdout).toContain('native-set ok: 8 binaries for mac, windows, linux present');
+ expect(short.status).toBe(1);
+ expect(short.stdout).toContain(`::error::native-set: ${CLI_NATIVE_DIR}/${ALL[0]} is missing`);
+ });
+
+ test('a refusal names the recovery section', () => {
+ const short = run(withParser(tree(ALL, { shipped: ALL.slice(1) })), [
+ 'platforms',
+ 'mac,windows,linux',
+ ]);
+ expect(short.stdout).toContain(`resume per RELEASES.md '${RECOVERY_SECTION}'`);
+ });
+
+ test('still asserts when it is run through a symlinked path', () => {
+ const linked = join(scratch('ok-native-set-link-'), 'scripts');
+ symlinkSync(dirname(SCRIPT), linked, 'dir');
+ const short = run(
+ withParser(tree(ALL, { shipped: ALL.slice(1) })),
+ ['platforms', 'mac,windows,linux'],
+ {
+ script: join(linked, 'assert-native-set.mjs'),
+ },
+ );
+ expect(short.status).toBe(1);
+ expect(short.stdout).toContain(`::error::native-set: ${CLI_NATIVE_DIR}/${ALL[0]} is missing`);
+ });
+
+ test('exits 1 when napi’s target parser cannot be loaded, instead of asserting nothing', () => {
+ const result = run(tree(ALL), ['platforms', 'mac,windows,linux']);
+ expect(result.status).toBe(1);
+ expect(result.stdout).toContain("::error::cannot load napi's target parser");
+ });
+
+ test('exits 1 on an unknown mode, or a platforms mode with no list, instead of asserting nothing', () => {
+ const unknown = run(withParser(tree(ALL)), ['some']);
+ expect(unknown.status).toBe(1);
+ expect(unknown.stdout).toContain('mode must be one of host, platforms, staged');
+ const unset = run(withParser(tree(ALL)), ['platforms', '']);
+ expect(unset.status).toBe(1);
+ expect(unset.stdout).toContain('platforms needs a comma-separated list');
+ });
+
+ test.skipIf(!RUNNER_BINARY)(
+ 'a host run through the entry point passes the binary this runner builds',
+ () => {
+ const result = run(withParser(tree([RUNNER_BINARY])), ['host']);
+ expect(result.status).toBe(0);
+ expect(result.stdout).toContain('native-set ok: 1 binaries for host present');
+ },
+ );
+
+ test('the staging verdict writes the packaged platforms, warns loudly on a drop and refuses a required gap', () => {
+ const dropRoot = withParser(
+ tree(without(ALL, 'native-config.win32-x64-msvc.node'), { shipped: [] }),
+ );
+ const dropFiles = outputs(dropRoot);
+ const drop = run(dropRoot, staged('windows,linux', 'mac,linux'), { env: dropFiles });
+ expect(drop.status).toBe(0);
+ expect(drop.stdout).toContain(
+ '::warning::DEGRADED CUT: windows is not a required platform, and its staged native-config set is missing native-config.win32-x64-msvc.node (staged from run 1), so windows is not packaged or shipped this cut.',
+ );
+ expect(readFileSync(dropFiles.GITHUB_OUTPUT, 'utf8')).toBe('platforms=linux\n');
+ expect(readFileSync(dropFiles.GITHUB_STEP_SUMMARY, 'utf8')).toContain('Degraded cut: windows');
+
+ const gapRoot = withParser(
+ tree(without(ALL, 'native-config.win32-x64-msvc.node'), { shipped: [] }),
+ );
+ const gapFiles = outputs(gapRoot);
+ const gap = run(gapRoot, staged('windows,linux', 'mac,windows,linux'), {
+ env: gapFiles,
+ });
+ expect(gap.status).toBe(1);
+ expect(gap.stdout).toContain(
+ `::error::native-set: windows is a required platform, and its staged native-config set is missing native-config.win32-x64-msvc.node (staged from run 1). Re-run the prebuild, then resume per RELEASES.md '${RECOVERY_SECTION}'.`,
+ );
+ expect(gap.stdout).not.toContain('::warning::');
+ expect(readFileSync(gapFiles.GITHUB_OUTPUT, 'utf8')).toBe('');
+ });
+
+ test('the staging verdict exits 1 naming a served platform that owns no declared target', () => {
+ const root = withParser(tree(ALL, { declared: undeclaring('win32'), shipped: [] }));
+ const files = outputs(root);
+ const result = run(root, staged('windows,linux', 'mac'), { env: files });
+ expect(result.status).toBe(1);
+ expect(result.stdout).toContain(`::error::native-set: ${NO_WINDOWS_TARGET}`);
+ expect(readFileSync(files.GITHUB_OUTPUT, 'utf8')).toBe('');
+ });
+
+ test('the staging verdict writes none when every platform it serves is dropped', () => {
+ const root = withParser(tree([], { shipped: [] }));
+ const files = outputs(root);
+ const result = run(root, staged('windows,linux', 'mac'), { env: files });
+ expect(result.status).toBe(0);
+ expect(readFileSync(files.GITHUB_OUTPUT, 'utf8')).toBe('platforms=none\n');
+ });
+});
diff --git a/.github/scripts/select-native-config-prebuild.mjs b/.github/scripts/select-native-config-prebuild.mjs
index 4cbe5dc07..987feea84 100644
--- a/.github/scripts/select-native-config-prebuild.mjs
+++ b/.github/scripts/select-native-config-prebuild.mjs
@@ -91,19 +91,40 @@ export function listPrebuildRuns({
);
}
+function failureOf(res) {
+ if (res.error) return `failed to spawn: ${res.error.message}`;
+ if (res.signal) return `killed by signal ${res.signal}`;
+ const stderr = String(res.stderr || '').trim();
+ return `failed (exit ${res.status})${stderr ? `: ${stderr}` : ''}`;
+}
+
+function makeGitAnswer(run) {
+ return (args) => {
+ const res = run('git', args, { encoding: 'utf8' });
+ if (res.error || res.signal || (res.status !== 0 && res.status !== 1)) {
+ throw new Error(`git ${args.join(' ')} ${failureOf(res)}`);
+ }
+ return { yes: res.status === 0, stdout: String(res.stdout || '').trim() };
+ };
+}
+
export function makeIsAncestor(run = spawnSync) {
+ const git = makeGitAnswer(run);
return (sha, ref) =>
- run('git', ['merge-base', '--is-ancestor', sha, ref], { encoding: 'utf8' }).status === 0;
+ git(['rev-parse', '--verify', '--quiet', `${sha}^{commit}`]).yes &&
+ git(['merge-base', '--is-ancestor', sha, ref]).yes;
}
export function makeTreeAt(run = spawnSync) {
+ const git = makeGitAnswer(run);
return (ref) => {
- const res = run('git', ['rev-parse', '--verify', `${ref}:${NATIVE_CONFIG_PATH}`], {
- encoding: 'utf8',
- });
- if (res.status !== 0) return null;
- const tree = String(res.stdout || '').trim();
- return tree === '' ? null : tree;
+ const { yes, stdout } = git([
+ 'rev-parse',
+ '--verify',
+ '--quiet',
+ `${ref}:${NATIVE_CONFIG_PATH}`,
+ ]);
+ return yes && stdout !== '' ? stdout : null;
};
}
diff --git a/.github/scripts/select-native-config-prebuild.test.mjs b/.github/scripts/select-native-config-prebuild.test.mjs
index f6f920bd9..0f07ebddb 100644
--- a/.github/scripts/select-native-config-prebuild.test.mjs
+++ b/.github/scripts/select-native-config-prebuild.test.mjs
@@ -1,9 +1,19 @@
import { spawnSync } from 'node:child_process';
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import {
+ copyFileSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ rmSync,
+ symlinkSync,
+ writeFileSync,
+} from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { describe, expect, test } from 'vitest';
+import { parse } from 'yaml';
+import { gitCleanEnv } from '../../scripts/git-clean-env.mjs';
import {
DEFAULT_CANDIDATE_LIMIT,
describeNoSelection,
@@ -28,9 +38,9 @@ const stagingStep = (yaml) => {
const stagingFunctions = (yaml) => {
const step = stagingStep(yaml);
- const start = step.indexOf(' summarize() {');
+ const start = step.search(/^ {10}[a-z_]+\(\) \{$/m);
const close = '\n }\n';
- const end = step.indexOf(close, step.indexOf(' degrade_or_fail() {'));
+ const end = step.indexOf(close, step.indexOf(' judge_staging() {'));
if (start === -1 || end === -1) throw new Error('no staging function block in the step');
return step
.slice(start, end + close.length)
@@ -39,35 +49,66 @@ const stagingFunctions = (yaml) => {
.join('\n');
};
-const runDegradeOrFail = (functions, { isStable, staged }) => {
+const stagingDeclarations = (yaml) => {
+ const document = parse(yaml);
+ const job = Object.values(document.jobs).find(({ steps }) =>
+ steps?.some((step) => step.name === 'Stage native-config prebuilt binaries'),
+ );
+ const step = job.steps.find(({ name }) => name === 'Stage native-config prebuilt binaries');
+ return { document, job, step };
+};
+
+const stagingEnv = (yaml) => stagingDeclarations(yaml).step.env;
+
+const runnerBashArgs = (yaml) => {
+ const { document, job, step } = stagingDeclarations(yaml);
+ const shell = step.shell ?? job.defaults?.run?.shell ?? document.defaults?.run?.shell;
+ if (shell === undefined) return ['-e'];
+ if (shell === 'bash') return ['--noprofile', '--norc', '-e', '-o', 'pipefail'];
+ throw new Error(`no runner argument format for the staging step's shell: ${shell}`);
+};
+
+const NATIVE_CONFIG = join(REPO_ROOT, 'packages', 'native-config');
+const JUDGE = join(REPO_ROOT, '.github', 'scripts', 'assert-native-set.mjs');
+const { NODE_PATH: _pnpmShimPath, ...judgeEnv } = process.env;
+
+const runJudge = (yaml, { staged, env }) => {
const dir = mkdtempSync(join(tmpdir(), 'ok-native-staging-'));
try {
- mkdirSync(join(dir, 'packages', 'native-config'), { recursive: true });
+ const nativeConfig = join(dir, 'packages', 'native-config');
+ mkdirSync(nativeConfig, { recursive: true });
+ writeFileSync(
+ join(nativeConfig, 'package.json'),
+ readFileSync(join(NATIVE_CONFIG, 'package.json')),
+ );
+ symlinkSync(join(NATIVE_CONFIG, 'node_modules'), join(nativeConfig, 'node_modules'));
for (const target of staged) {
- writeFileSync(join(dir, 'packages', 'native-config', `native-config.${target}.node`), '');
+ writeFileSync(join(nativeConfig, `native-config.${target}.node`), `bytes of ${target}`);
}
+ const files = { GITHUB_OUTPUT: join(dir, 'output'), GITHUB_STEP_SUMMARY: join(dir, 'summary') };
+ for (const file of Object.values(files)) writeFileSync(file, '');
const script = join(dir, 'staging.sh');
writeFileSync(
script,
- `${functions}\ndegrade_or_fail "could not download native-config-bindings-all from run 1" "0/8"\n`,
+ `${stagingFunctions(yaml)}\njudge="${JUDGE}"\njudge_staging "staged from run 1"\n`,
);
- const result = spawnSync('bash', [script], {
+ const result = spawnSync('bash', [...runnerBashArgs(yaml), script], {
encoding: 'utf8',
- timeout: 10_000,
+ timeout: 30_000,
cwd: dir,
- env: {
- ...process.env,
- IS_STABLE: String(isStable),
- GITHUB_STEP_SUMMARY: join(dir, 'step-summary.txt'),
- },
+ env: { ...judgeEnv, ...env, ...files },
});
- return { status: result.status, output: `${result.stdout}${result.stderr}` };
+ return {
+ status: result.status,
+ output: `${result.stdout}${result.stderr}`,
+ outputs: readFileSync(files.GITHUB_OUTPUT, 'utf8'),
+ };
} finally {
rmSync(dir, { recursive: true, force: true });
}
};
-const runDownloadBindings = (functions, { failures }) => {
+const runDownloadBindings = (yaml, { failures }) => {
const dir = mkdtempSync(join(tmpdir(), 'ok-native-download-'));
try {
const bin = join(dir, 'bin');
@@ -80,19 +121,21 @@ const runDownloadBindings = (functions, { failures }) => {
);
spawnSync('chmod', ['+x', join(bin, 'gh')]);
const script = join(dir, 'download.sh');
+ const functions = stagingFunctions(yaml);
if (!functions.includes('/tmp/nc-bindings')) {
- throw new Error('staging bytes no longer name /tmp/nc-bindings; the rescope would silently no-op');
+ throw new Error(
+ 'staging bytes no longer name /tmp/nc-bindings; the rescope would silently no-op',
+ );
}
const scoped = functions.replaceAll('/tmp/nc-bindings', bindingsDir);
writeFileSync(script, `${scoped}\ndownload_bindings 1\n`);
- const result = spawnSync('bash', [script], {
+ const result = spawnSync('bash', [...runnerBashArgs(yaml), script], {
encoding: 'utf8',
timeout: 60_000,
cwd: dir,
env: {
...process.env,
PATH: `${bin}:${process.env.PATH}`,
- IS_STABLE: 'false',
NC_RETRY_BACKOFF_S: '0',
},
});
@@ -103,11 +146,63 @@ const runDownloadBindings = (functions, { failures }) => {
}
};
-const BOTH_WINDOWS_TARGETS = ['win32-x64-msvc', 'win32-arm64-msvc'];
+const runQaStaging = ({ gh, platforms }) => {
+ const dir = mkdtempSync(join(tmpdir(), 'ok-qa-staging-'));
+ try {
+ const nativeConfig = join(dir, 'packages', 'native-config');
+ mkdirSync(nativeConfig, { recursive: true });
+ writeFileSync(
+ join(nativeConfig, 'package.json'),
+ readFileSync(join(NATIVE_CONFIG, 'package.json')),
+ );
+ symlinkSync(join(NATIVE_CONFIG, 'node_modules'), join(nativeConfig, 'node_modules'));
+ mkdirSync(join(dir, '.github', 'scripts'), { recursive: true });
+ copyFileSync(JUDGE, join(dir, '.github', 'scripts', 'assert-native-set.mjs'));
+ const bin = join(dir, 'bin');
+ mkdirSync(bin);
+ writeFileSync(join(bin, 'gh'), `#!/bin/bash\n${gh}\n`, { mode: 0o755 });
+ const yaml = workflow('desktop-build-win-linux.yml');
+ const script = join(dir, 'staging.sh');
+ writeFileSync(script, stagingDeclarations(yaml).step.run);
+ const files = { GITHUB_OUTPUT: join(dir, 'output'), GITHUB_STEP_SUMMARY: join(dir, 'summary') };
+ for (const file of Object.values(files)) writeFileSync(file, '');
+ const result = spawnSync('bash', [...runnerBashArgs(yaml), script], {
+ encoding: 'utf8',
+ timeout: 30_000,
+ cwd: dir,
+ env: {
+ ...gitCleanEnv(judgeEnv),
+ ...files,
+ GIT_CEILING_DIRECTORIES: dirname(dir),
+ GITHUB_SHA: '0000000000000000000000000000000000000000',
+ PATH: `${bin}:${process.env.PATH}`,
+ PLATFORMS: platforms,
+ RUNNER_TEMP: dir,
+ },
+ });
+ return { status: result.status, output: `${result.stdout}${result.stderr}` };
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+};
+
+const EVERY_TARGET = [
+ 'darwin-arm64',
+ 'darwin-x64',
+ 'linux-arm64-gnu',
+ 'linux-arm64-musl',
+ 'linux-x64-gnu',
+ 'linux-x64-musl',
+ 'win32-arm64-msvc',
+ 'win32-x64-msvc',
+];
+const LINUX_TARGETS = EVERY_TARGET.filter((target) => target.startsWith('linux-'));
+const allBut = (targets, missing) => targets.filter((target) => target !== missing);
const REFUSAL_RECOVERY_SECTION = {
- 'release.yml': 'Native addon staging (Windows is mandatory)',
+ 'release.yml': 'Native addon staging',
'desktop-release.yml': 'Resuming a blocked cut',
+ 'desktop-build-win-linux.yml': 'Native addon staging',
};
const chainFixture = (chain) => {
@@ -261,9 +356,27 @@ describe('step extraction', () => {
});
describe('git boundary', () => {
- test('isAncestor reads a non-zero exit as "not an ancestor"', () => {
+ const failures = [
+ [
+ 'an exit status git reserves for errors',
+ { status: 128, stdout: '', stderr: 'fatal: not a git repository' },
+ 'fatal: not a git repository',
+ ],
+ [
+ 'a git that could not be spawned',
+ { status: null, error: new Error('spawn git ENOENT') },
+ 'spawn git ENOENT',
+ ],
+ [
+ 'a git killed by a signal',
+ { status: null, signal: 'SIGKILL', stdout: '', stderr: '' },
+ 'SIGKILL',
+ ],
+ ];
+
+ test('isAncestor answers only on exit 0 and exit 1', () => {
const isAncestor = makeIsAncestor((_cmd, args) => ({
- status: args.includes('good') ? 0 : 1,
+ status: args.some((arg) => arg.startsWith('good')) ? 0 : 1,
stdout: '',
stderr: '',
}));
@@ -271,11 +384,101 @@ describe('git boundary', () => {
expect(isAncestor('missing', 'HEAD')).toBe(false);
});
- test('treeAt returns null for an unresolvable path', () => {
- const treeAt = makeTreeAt(() => ({ status: 128, stdout: '', stderr: 'bad revision' }));
+ test.each(failures)(
+ 'isAncestor throws when merge-base fails on %s after the candidate is found',
+ (_label, result, cause) => {
+ const isAncestor = makeIsAncestor((_cmd, args) =>
+ args[0] === 'rev-parse' ? { status: 0, stdout: 'aaaaaaa\n', stderr: '' } : result,
+ );
+ expect(() => isAncestor('good', 'HEAD')).toThrow(cause);
+ },
+ );
+
+ test('isAncestor reads a candidate commit absent from the clone as not an ancestor', () => {
+ const asked = [];
+ const isAncestor = makeIsAncestor((_cmd, args) => {
+ asked.push(args[0]);
+ return args[0] === 'rev-parse'
+ ? { status: 1, stdout: '', stderr: '' }
+ : { status: 128, stdout: '', stderr: 'fatal: Not a valid commit name' };
+ });
+ expect(isAncestor('gone', 'HEAD')).toBe(false);
+ expect(asked).toEqual(['rev-parse']);
+ });
+
+ test('against real git: absent commits and paths are answers, and a missing repository throws', () => {
+ const repo = mkdtempSync(join(tmpdir(), 'ok-select-prebuild-git-'));
+ const outside = mkdtempSync(join(tmpdir(), 'ok-select-prebuild-nogit-'));
+ const env = { ...gitCleanEnv(), GIT_CEILING_DIRECTORIES: dirname(outside) };
+ try {
+ const git = (...args) =>
+ spawnSync(
+ 'git',
+ [
+ '-c',
+ 'user.name=Test',
+ '-c',
+ '-c',
+ 'commit.gpgsign=false',
+ ...args,
+ ],
+ { cwd: repo, encoding: 'utf8', env },
+ ).stdout.trim();
+ git('init', '--quiet', '--initial-branch=main');
+ git('commit', '--quiet', '--allow-empty', '-m', 'before native-config');
+ const first = git('rev-parse', 'HEAD');
+ mkdirSync(join(repo, 'packages', 'native-config'), { recursive: true });
+ writeFileSync(join(repo, 'packages', 'native-config', 'Cargo.toml'), '[package]\n');
+ git('add', '.');
+ git('commit', '--quiet', '-m', 'native-config');
+ const inRepo = (cmd, args, options) => spawnSync(cmd, args, { ...options, cwd: repo, env });
+ const isAncestor = makeIsAncestor(inRepo);
+ const treeAt = makeTreeAt(inRepo);
+ expect(isAncestor(first, 'HEAD')).toBe(true);
+ expect(isAncestor('HEAD', first)).toBe(false);
+ expect(isAncestor('0123456789abcdef0123456789abcdef01234567', 'HEAD')).toBe(false);
+ expect(() => isAncestor(first, 'no-such-ref')).toThrow(
+ /merge-base --is-ancestor .*no-such-ref/,
+ );
+ expect(treeAt('HEAD')).toMatch(/^[0-9a-f]{40}$/);
+ expect(treeAt(first)).toBeNull();
+ const inNoRepo = (cmd, args, options) =>
+ spawnSync(cmd, args, { ...options, cwd: outside, env });
+ expect(() => makeIsAncestor(inNoRepo)(first, 'HEAD')).toThrow('not a git repository');
+ expect(() => makeTreeAt(inNoRepo)('HEAD')).toThrow('not a git repository');
+ } finally {
+ rmSync(repo, { recursive: true, force: true });
+ rmSync(outside, { recursive: true, force: true });
+ }
+ });
+
+ test.each(failures)(
+ 'isAncestor throws on %s instead of answering "not an ancestor"',
+ (_label, result, cause) => {
+ const isAncestor = makeIsAncestor(() => result);
+ expect(() => isAncestor('good', 'HEAD')).toThrow(cause);
+ },
+ );
+
+ test('treeAt asks git quietly and reads exit 1 as an absent path', () => {
+ let seen = [];
+ const treeAt = makeTreeAt((_cmd, args) => {
+ seen = args;
+ return { status: 1, stdout: '', stderr: '' };
+ });
expect(treeAt('HEAD')).toBeNull();
+ expect(seen).toContain('--quiet');
});
+ test.each(failures)(
+ 'treeAt throws on %s instead of answering "absent"',
+ (_label, result, cause) => {
+ const treeAt = makeTreeAt(() => result);
+ expect(() => treeAt('HEAD')).toThrow(cause);
+ },
+ );
+
test('treeAt trims the tree object it reports', () => {
const treeAt = makeTreeAt(() => ({ status: 0, stdout: 'eb09e361\n', stderr: '' }));
expect(treeAt('HEAD')).toBe('eb09e361');
@@ -424,82 +627,186 @@ describe('workflow wiring', () => {
expect(step).toContain('cp .github/scripts/select-native-config-prebuild.mjs');
});
- test(`${name} still splits beta degradation from stable refusal`, () => {
+ test(`${name} retries the bindings download a bounded number of times`, () => {
+ const yaml = workflow(name);
+ const recovered = runDownloadBindings(yaml, { failures: 2 });
+ expect(recovered.status).toBe(0);
+ expect(recovered.calls).toBe(3);
+ const exhausted = runDownloadBindings(yaml, { failures: 99 });
+ expect(exhausted.status).not.toBe(0);
+ expect(exhausted.calls).toBe(3);
+ });
+
+ test(`${name} asserts the selector's output shape, not just non-emptiness`, () => {
const step = stagingStep(workflow(name));
- expect(step).toContain('degrade_or_fail');
+ expect(step).toContain("selection_shape='^[0-9]+'$'\\t''[0-9a-f]{7,40}$'");
expect(step).toMatch(
- /if \[ "\$IS_STABLE" = "true" \]; then\n\s+echo "::error::[^\n]+\n\s+exit 1/,
+ /if \[\[ ! \$selection =~ \$selection_shape \]\]; then\n\s+flattened=[^\n]*\n\s+judge_staging[^\n]*\n\s+fi/,
);
- expect(step).toMatch(/echo "::warning::[^\n]+\n\s+exit 0/);
});
+ }
- test(`${name} requires both Windows binaries at every staging outcome`, () => {
+ for (const name of ['desktop-release.yml', 'release.yml', 'desktop-build-win-linux.yml']) {
+ test(`${name} judges staging with the native-set judge from the workflow's own commit, on every path`, () => {
const step = stagingStep(workflow(name));
- for (const target of BOTH_WINDOWS_TARGETS) {
- expect(step).toContain(`native-config.${target}.node`);
- }
- expect(step).toMatch(/summarize "\$2 — \$1"\n\s+require_windows_targets "\$1"/);
- expect(step).toMatch(/-lt 8 \]; then\n(?:.*\n)*?\s+fi\n\s+require_windows_targets /);
+ expect(step).toContain('$GITHUB_SHA:.github/scripts/assert-native-set.mjs');
+ expect(step).toContain('cp .github/scripts/assert-native-set.mjs');
+ expect(step).toContain('id: stage');
+ expect(step).not.toMatch(/\bexit 0\b/);
+ expect(step).not.toContain('degrade_or_fail');
+ expect(step).toMatch(
+ /judge_staging "staged \$count native-config binaries from run \$run_id/,
+ );
});
+ }
- test(`${name} refuses a beta cut whose staged set lacks either Windows binary`, () => {
- const functions = stagingFunctions(workflow(name));
- expect(functions).toContain('require_windows_targets');
+ test('release.yml requires every platform, because one npm tarball carries them all', () => {
+ expect(stagingEnv(workflow('release.yml'))).toMatchObject({
+ SERVES: 'mac,windows,linux',
+ REQUIRES: 'mac,windows,linux',
+ });
+ const yaml = workflow('release.yml');
+ const env = stagingEnv(yaml);
+ const complete = runJudge(yaml, { staged: EVERY_TARGET, env });
+ expect(complete.status).toBe(0);
+ expect(complete.outputs).toBe('platforms=mac,windows,linux\n');
+ const gap = runJudge(yaml, { staged: allBut(EVERY_TARGET, 'linux-arm64-musl'), env });
+ expect(gap.status).toBe(1);
+ expect(gap.output).toContain(
+ '::error::native-set: linux is a required platform, and its staged native-config set is missing native-config.linux-arm64-musl.node',
+ );
+ expect(gap.output).toContain(
+ `resume per RELEASES.md '${REFUSAL_RECOVERY_SECTION['release.yml']}'`,
+ );
+ expect(gap.output).not.toContain('::warning::');
+ });
- const recovered = runDownloadBindings(functions, { failures: 2 });
- expect(recovered.status).toBe(0);
- expect(recovered.calls).toBe(3);
- const exhausted = runDownloadBindings(functions, { failures: 99 });
- expect(exhausted.status).not.toBe(0);
- expect(exhausted.calls).toBe(3);
+ test('desktop-release.yml reads the channel and the required platforms into its staging step', () => {
+ expect(stagingEnv(workflow('desktop-release.yml'))).toEqual({
+ GH_TOKEN: `\${{ github.token }}`,
+ CHANNEL: `\${{ steps.channel.outputs.channel }}`,
+ REQUIRED: `\${{ steps.required.outputs.required }}`,
+ });
+ });
+
+ test('desktop-release.yml requires every platform on a stable cut, whatever the required platforms say', () => {
+ const yaml = workflow('desktop-release.yml');
+ const stable = { CHANNEL: 'latest', REQUIRED: 'mac,linux' };
+
+ const complete = runJudge(yaml, { staged: EVERY_TARGET, env: stable });
+ expect(complete.status).toBe(0);
+ expect(complete.outputs).toBe('platforms=mac,windows,linux\n');
- const complete = runDegradeOrFail(functions, {
- isStable: false,
- staged: BOTH_WINDOWS_TARGETS,
- });
- expect(complete.status).toBe(0);
- expect(complete.output).toContain('::warning::');
- expect(complete.output).not.toContain('::error::');
-
- for (const missing of BOTH_WINDOWS_TARGETS) {
- const staged = BOTH_WINDOWS_TARGETS.filter((target) => target !== missing);
- const refused = runDegradeOrFail(functions, { isStable: false, staged });
- expect(refused.status).toBe(1);
- expect(refused.output).toContain(`native-config.${missing}.node was not staged`);
- expect(refused.output).not.toContain('::warning::');
- expect(refused.output).toContain(
- `resume per RELEASES.md '${REFUSAL_RECOVERY_SECTION[name]}'`,
- );
- }
+ const gap = runJudge(yaml, {
+ staged: allBut(EVERY_TARGET, 'win32-x64-msvc'),
+ env: stable,
});
+ expect(gap.status).toBe(1);
+ expect(gap.output).toContain(
+ '::error::native-set: windows is a required platform, and its staged native-config set is missing native-config.win32-x64-msvc.node',
+ );
+ expect(gap.output).not.toContain('::warning::');
+ expect(gap.outputs).toBe('');
- test(`${name} still refuses a stable cut with a complete Windows pair`, () => {
- const refused = runDegradeOrFail(stagingFunctions(workflow(name)), {
- isStable: true,
- staged: BOTH_WINDOWS_TARGETS,
- });
- expect(refused.status).toBe(1);
- expect(refused.output).toContain('incomplete native-config binary set');
- expect(refused.output).not.toContain('::warning::');
+ const darwinGap = runJudge(yaml, {
+ staged: allBut(EVERY_TARGET, 'darwin-arm64'),
+ env: stable,
});
+ expect(darwinGap.status).toBe(1);
+ expect(darwinGap.output).toContain(
+ '::error::native-set: mac is a required platform, and its staged native-config set is missing native-config.darwin-arm64.node',
+ );
+ });
- test(`${name} names the missing Windows binary on the stable channel too`, () => {
- const functions = stagingFunctions(workflow(name));
- for (const missing of BOTH_WINDOWS_TARGETS) {
- const staged = BOTH_WINDOWS_TARGETS.filter((target) => target !== missing);
- const refused = runDegradeOrFail(functions, { isStable: true, staged });
- expect(refused.status).toBe(1);
- expect(refused.output).toContain(`native-config.${missing}.node was not staged`);
- expect(refused.output).not.toContain('incomplete native-config binary set');
- }
+ test('desktop-release.yml judges a beta cut’s Windows and Linux bundle against the required platforms', () => {
+ const yaml = workflow('desktop-release.yml');
+ const base = { CHANNEL: 'beta' };
+
+ const requiredGap = runJudge(yaml, {
+ staged: allBut(EVERY_TARGET, 'win32-arm64-msvc'),
+ env: { ...base, REQUIRED: 'mac,windows,linux' },
});
+ expect(requiredGap.status).toBe(1);
+ expect(requiredGap.output).toContain(
+ '::error::native-set: windows is a required platform, and its staged native-config set is missing native-config.win32-arm64-msvc.node',
+ );
+ expect(requiredGap.output).toContain(
+ `resume per RELEASES.md '${REFUSAL_RECOVERY_SECTION['desktop-release.yml']}'`,
+ );
+ expect(requiredGap.outputs).toBe('');
- test(`${name} asserts the selector's output shape, not just non-emptiness`, () => {
- const step = stagingStep(workflow(name));
- expect(step).toContain("selection_shape='^[0-9]+'$'\\t''[0-9a-f]{7,40}$'");
- expect(step).toMatch(
- /if \[\[ ! \$selection =~ \$selection_shape \]\]; then\n\s+flattened=[^\n]*\n\s+degrade_or_fail[^\n]*\n\s+fi/,
- );
+ const droppedGap = runJudge(yaml, {
+ staged: allBut(EVERY_TARGET, 'win32-x64-msvc'),
+ env: { ...base, REQUIRED: 'mac,linux' },
});
- }
+ expect(droppedGap.status).toBe(0);
+ expect(droppedGap.output).toContain(
+ '::warning::DEGRADED CUT: windows is not a required platform',
+ );
+ expect(droppedGap.output).not.toContain('::error::');
+ expect(droppedGap.outputs).toBe('platforms=linux\n');
+
+ const complete = runJudge(yaml, {
+ staged: EVERY_TARGET,
+ env: { ...base, REQUIRED: 'mac,linux' },
+ });
+ expect(complete.status).toBe(0);
+ expect(complete.outputs).toBe('platforms=windows,linux\n');
+ });
+
+ test('desktop-release.yml packages only the platforms staging kept, and publishes them from prepare', () => {
+ const { jobs } = parse(workflow('desktop-release.yml'));
+ expect(jobs.prepare.outputs.platforms).toBe(`\${{ steps.stage.outputs.platforms }}`);
+ expect(jobs['build-windows'].if).toBe("contains(needs.prepare.outputs.platforms, 'windows')");
+ expect(jobs['build-linux'].if).toBe("contains(needs.prepare.outputs.platforms, 'linux')");
+ });
+
+ test('desktop-build-win-linux.yml requires exactly the platforms a QA dispatch builds', () => {
+ const yaml = workflow('desktop-build-win-linux.yml');
+ expect(stagingEnv(yaml)).toMatchObject({ PLATFORMS: `\${{ inputs.platforms }}` });
+
+ const linuxOnly = runJudge(yaml, { staged: LINUX_TARGETS, env: { PLATFORMS: 'linux' } });
+ expect(linuxOnly.status).toBe(0);
+ expect(linuxOnly.outputs).toBe('platforms=linux\n');
+
+ const linuxGap = runJudge(yaml, {
+ staged: allBut(LINUX_TARGETS, 'linux-x64-gnu'),
+ env: { PLATFORMS: 'linux' },
+ });
+ expect(linuxGap.status).toBe(1);
+ expect(linuxGap.output).toContain(
+ '::error::native-set: linux is a required platform, and its staged native-config set is missing native-config.linux-x64-gnu.node',
+ );
+ expect(linuxGap.output).toContain(
+ `RELEASES.md '${REFUSAL_RECOVERY_SECTION['desktop-build-win-linux.yml']}'`,
+ );
+
+ const both = runJudge(yaml, { staged: EVERY_TARGET, env: { PLATFORMS: 'both' } });
+ expect(both.status).toBe(0);
+ expect(both.outputs).toBe('platforms=windows,linux\n');
+ });
+
+ test('desktop-build-win-linux.yml tells a failed prebuild-run query apart from an empty one', () => {
+ const failed = runQaStaging({
+ gh: "echo 'HTTP 502: Bad Gateway' >&2\nexit 1",
+ platforms: 'linux',
+ });
+ expect(failed.status).toBe(1);
+ expect(failed.output).toContain(
+ '(could not list native-config-prebuild runs on main: HTTP 502: Bad Gateway)',
+ );
+ expect(failed.output).not.toContain('no successful native-config-prebuild run found');
+
+ const empty = runQaStaging({ gh: 'exit 0', platforms: 'linux' });
+ expect(empty.status).toBe(1);
+ expect(empty.output).toContain('(no successful native-config-prebuild run found on main)');
+ });
+
+ test('desktop-build-win-linux.yml names a cause when a failed prebuild-run query prints nothing', () => {
+ const silent = runQaStaging({ gh: 'exit 4', platforms: 'linux' });
+ expect(silent.status).toBe(1);
+ expect(silent.output).toContain(
+ '(could not list native-config-prebuild runs on main: gh run list exited 4 with no error output)',
+ );
+ });
});
diff --git a/.github/workflows/desktop-build-win-linux.yml b/.github/workflows/desktop-build-win-linux.yml
index 91638ed1b..c86eb67ef 100644
--- a/.github/workflows/desktop-build-win-linux.yml
+++ b/.github/workflows/desktop-build-win-linux.yml
@@ -89,35 +89,47 @@ jobs:
restore-keys: |
${{ runner.os }}-ok-pnpm-store-
- - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
- with:
- path: .turbo
- key: ${{ runner.os }}-turbo-desktop-manual-${{ hashFiles('pnpm-lock.yaml') }}
- restore-keys: |
- ${{ runner.os }}-turbo-desktop-manual-
- ${{ runner.os }}-turbo-desktop-
-
- name: Install dependencies
run: pnpm install --frozen-lockfile
- - name: Stage native-config prebuilt binaries (best-effort)
+ - name: Stage native-config prebuilt binaries
+ id: stage
env:
GH_TOKEN: ${{ github.token }}
+ PLATFORMS: ${{ inputs.platforms }}
run: |
set -uo pipefail
+ judge_staging() {
+ if [ ! -s "$judge" ]; then
+ echo "::error::the native-set judge is missing at $GITHUB_SHA and in the checkout; refusing this QA build"
+ exit 1
+ fi
+ node "$judge" staged --serves "${PLATFORMS/both/windows,linux}" --requires "${PLATFORMS/both/windows,linux}" --reason "$1" \
+ --recovery "Re-dispatch this workflow once native-config-prebuild.yml has a green run on main whose native-config-bindings-all artifact is complete (RELEASES.md 'Native addon staging')."
+ exit $?
+ }
+ judge="${RUNNER_TEMP:-/tmp}/assert-native-set.mjs"
+ if ! git show "$GITHUB_SHA:.github/scripts/assert-native-set.mjs" > "$judge" 2>/dev/null; then
+ cp .github/scripts/assert-native-set.mjs "$judge" 2>/dev/null || true
+ fi
+ list_err="${RUNNER_TEMP:-/tmp}/native-config-list.err"
+ list_rc=0
run_id=$(gh run list --workflow=native-config-prebuild.yml --branch main --event push \
- --status success --limit 1 --json databaseId --jq '.[0].databaseId // empty' 2>/dev/null || true)
+ --status success --limit 1 --json databaseId --jq '.[0].databaseId // empty' 2>"$list_err") || list_rc=$?
+ if [ "$list_rc" -ne 0 ]; then
+ reason=$(tr '\n' ' ' < "$list_err" | sed 's/ *$//')
+ judge_staging "could not list native-config-prebuild runs on main: ${reason:-gh run list exited $list_rc with no error output}"
+ fi
if [ -z "$run_id" ]; then
- echo "::warning::no successful native-config-prebuild run found; Windows cleanup requires the native addon; QA artifacts may lack it"
- exit 0
+ judge_staging "no successful native-config-prebuild run found on main"
fi
if ! gh run download "$run_id" --name native-config-bindings-all --dir /tmp/nc-bindings; then
- echo "::warning::could not download native-config-bindings-all from run $run_id; Windows cleanup requires the native addon; QA artifacts may lack it"
- exit 0
+ judge_staging "could not download native-config-bindings-all from run $run_id"
fi
find /tmp/nc-bindings -name '*.node' -exec cp -f {} packages/native-config/ \;
count=$(find packages/native-config -maxdepth 1 -name '*.node' | wc -l | tr -d ' ')
echo "staged $count native-config prebuilt binaries from run $run_id"
+ judge_staging "staged $count native-config binaries from run $run_id"
# The workspace build produces native-config's host `.node` via `napi
# build` (turbo dep of the cli build), which needs a Rust toolchain —
@@ -127,12 +139,18 @@ jobs:
with:
toolchain: stable
- # Same two-filter sequencing as desktop-release.yml: app must build
- # before cli's build:assets copies app/dist into cli/dist/public.
- name: Build workspace (produces packages/cli/dist for extraResources)
run: |
- pnpm exec turbo run build --filter=@inkeep/open-knowledge-app
- pnpm exec turbo run build --filter=@inkeep/open-knowledge
+ pnpm exec turbo run build --filter=@inkeep/open-knowledge --cache=local:,remote:
+
+ - name: Assert the native-config binary set
+ env:
+ NATIVE_SET_PLATFORMS: ${{ steps.stage.outputs.platforms }}
+ run: |
+ set -euo pipefail
+ git cat-file -e "$GITHUB_SHA^{commit}" 2>/dev/null || git fetch --no-tags --depth=1 origin "$GITHUB_SHA"
+ git show "$GITHUB_SHA:.github/scripts/assert-native-set.mjs" > "$RUNNER_TEMP/assert-native-set.mjs"
+ node "$RUNNER_TEMP/assert-native-set.mjs" platforms "$NATIVE_SET_PLATFORMS"
# Hand the platform-neutral build products to the packaging jobs:
# the full bundled CLI tree + core/server dist + the native-config addon
diff --git a/.github/workflows/desktop-build.yml b/.github/workflows/desktop-build.yml
index 55bec10bc..0d1daa4b0 100644
--- a/.github/workflows/desktop-build.yml
+++ b/.github/workflows/desktop-build.yml
@@ -106,17 +106,6 @@ jobs:
restore-keys: |
${{ runner.os }}-ok-pnpm-store-
- # Turbo cache keeps `build` fast across runs. Keying on pnpm-lock.yaml
- # warm-caches across commits that don't change dependencies — cold
- # cache only when the lockfile actually moves. `github.sha` in the
- # restore-keys fallback still picks up same-commit re-runs.
- - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
- with:
- path: .turbo
- key: ${{ runner.os }}-turbo-desktop-${{ hashFiles('pnpm-lock.yaml') }}
- restore-keys: |
- ${{ runner.os }}-turbo-desktop-
-
- name: Install dependencies
# ELECTRON_SKIP_REBUILD=0 overrides the default CI skip in
# packages/desktop/scripts/postinstall.mjs — we *need* the native
@@ -125,31 +114,16 @@ jobs:
ELECTRON_SKIP_REBUILD: "0"
run: pnpm install --frozen-lockfile
- # electron-builder.yml's `extraResources` rule copies from
- # `packages/cli/dist/public/`, which the CLI's `build:assets` populates
- # via `cp -r ../app/dist dist/public`. The CLI does not declare the
- # app as a workspace dep (app is private, and the CLI ships the
- # compiled bundle — not a package reference), so turbo's `^build`
- # runs them in parallel by default. Without explicit sequencing, cli's
- # `build:assets` races app's vite build and can fail (no `app/dist`
- # yet) or copy stale content. Use turbo's `--filter=@inkeep/...`
- # which DOES respect the `^build` graph (so server + core build
- # before app), and run the two filters in sequence to enforce
- # app → cli ordering.
- #
- # A bare per-package `--filter` run was the previous approach; it does
- # not honor turbo's dep graph (only runs the named package's `build`
- # script in isolation). After the workspace started shipping
- # `.mjs` builds for `@inkeep/open-knowledge-server` and
- # `@inkeep/open-knowledge-core` (specs/2026-04-24-desktop-packaging-
- # first-boot/), Vite's config loader in app-build resolves those
- # workspace deps via `exports.default → ./dist/index.mjs`. Without
- # an upstream `^build`, the `dist/` doesn't exist yet → "Failed to
- # resolve entry for package @inkeep/open-knowledge-server".
- name: Build workspace (produces packages/cli/dist/public for extraResources)
run: |
- pnpm exec turbo run build --filter=@inkeep/open-knowledge-app
- pnpm exec turbo run build --filter=@inkeep/open-knowledge
+ pnpm exec turbo run build --filter=@inkeep/open-knowledge --cache=local:,remote:
+
+ - name: Assert the native-config binary set
+ run: |
+ set -euo pipefail
+ git cat-file -e "$GITHUB_SHA^{commit}" 2>/dev/null || git fetch --no-tags --depth=1 origin "$GITHUB_SHA"
+ git show "$GITHUB_SHA:.github/scripts/assert-native-set.mjs" > "$RUNNER_TEMP/assert-native-set.mjs"
+ node "$RUNNER_TEMP/assert-native-set.mjs" host
# Decide signed-vs-unsigned path BEFORE invoking electron-builder so
# the artifact can be named to match. We key off CSC_LINK alone: it's
diff --git a/.github/workflows/desktop-release.yml b/.github/workflows/desktop-release.yml
index c3a8c534b..b3c82aa6c 100644
--- a/.github/workflows/desktop-release.yml
+++ b/.github/workflows/desktop-release.yml
@@ -141,6 +141,7 @@ jobs:
product_name: ${{ steps.channel.outputs.product_name }}
artifact_name: ${{ steps.channel.outputs.artifact_name }}
required: ${{ steps.required.outputs.required }}
+ platforms: ${{ steps.stage.outputs.platforms }}
steps:
- name: Link to triggering run
# Back-link: promote-stable forwards its run URL in
@@ -225,7 +226,12 @@ jobs:
# subset of mac,windows,linux; unset = all three — fail-closed) names
# the platforms whose build failure blocks publication. Non-required
# platforms still BUILD every cut, and when their build succeeds their
- # assets still ship — requiredness only changes what can block. `mac`
+ # assets still ship — requiredness only changes what can block. On a
+ # beta cut the same set judges native-config staging: a gap in a
+ # required platform's set refuses the cut, and a non-required platform
+ # with a gap is not packaged that cut (its build job is skipped), never
+ # shipped without its binary. A stable cut's staging requires every
+ # platform whatever this variable says (see the staging step). `mac`
# can never be dropped: the stable DMG smoke gate (FR5b) and the npm
# dispatch hang off build-macos, so a mac-less release would ship
# unsmoked. A client on a platform missing from a cut simply 404s that
@@ -291,32 +297,19 @@ jobs:
restore-keys: |
${{ runner.os }}-ok-pnpm-store-
- - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
- with:
- path: .turbo
- key: ${{ runner.os }}-turbo-desktop-release-${{ hashFiles('pnpm-lock.yaml') }}
- restore-keys: |
- ${{ runner.os }}-turbo-desktop-release-
- ${{ runner.os }}-turbo-desktop-
-
- name: Install dependencies
run: pnpm install --frozen-lockfile
- name: Stage native-config prebuilt binaries
+ id: stage
env:
GH_TOKEN: ${{ github.token }}
- IS_STABLE: ${{ steps.channel.outputs.channel == 'latest' }}
+ CHANNEL: ${{ steps.channel.outputs.channel }}
+ REQUIRED: ${{ steps.required.outputs.required }}
run: |
summarize() {
echo "Staged native-config binaries: $1" >> "$GITHUB_STEP_SUMMARY"
}
- require_windows_targets() {
- for required in native-config.win32-x64-msvc.node native-config.win32-arm64-msvc.node; do
- if [ -f "packages/native-config/$required" ]; then continue; fi
- echo "::error::$1; $required was not staged, and the Windows installer built from this bundle would refuse removal without it. If no prebuild run matches this commit's packages/native-config tree, re-run native-config-prebuild.yml on an ancestor of this commit; if staging failed for another reason, re-run this workflow. Either way resume per RELEASES.md 'Resuming a blocked cut'."
- exit 1
- done
- }
download_bindings() {
for attempt in 1 2 3; do
rm -rf /tmp/nc-bindings
@@ -327,16 +320,20 @@ jobs:
done
return 1
}
- degrade_or_fail() {
- # $1: human-readable reason, $2: staged-count label for the summary
- summarize "$2 — $1"
- require_windows_targets "$1"
- if [ "$IS_STABLE" = "true" ]; then
- echo "::error::$1; refusing to cut a stable release with an incomplete native-config binary set"
+ judge_staging() {
+ summarize "$1"
+ if [ ! -s "$judge" ]; then
+ echo "::error::the native-set judge is missing at $GITHUB_SHA and in the release checkout; refusing this cut"
exit 1
fi
- echo "::warning::$1; both Windows binaries were staged, so only other targets are missing"
- exit 0
+ local serves=windows,linux requires="$REQUIRED"
+ if [ "$CHANNEL" = latest ]; then
+ serves=mac,windows,linux
+ requires=mac,windows,linux
+ fi
+ node "$judge" staged --serves "$serves" --requires "$requires" --reason "$1" \
+ --recovery "If no prebuild run matches this commit's packages/native-config tree, re-run native-config-prebuild.yml on an ancestor of this commit; if staging failed for another reason, re-run this workflow. Either way resume per RELEASES.md 'Resuming a blocked cut'."
+ exit $?
}
# Which prebuild run may be staged is release policy shared with the
@@ -356,18 +353,23 @@ jobs:
# checked-out copy. Pairing the two is what lets a re-fire on a stale
# tag run CURRENT release machinery rather than whatever was frozen in
# that tag, which is the only way re-firing a blocked release can ever
- # clear it. fetch-depth:0 in checkout has $GITHUB_SHA.
+ # clear it. fetch-depth:0 in checkout has $GITHUB_SHA. The native-set
+ # judge that decides what staging may package comes the same way.
+ judge="${RUNNER_TEMP:-/tmp}/assert-native-set.mjs"
+ if ! git show "$GITHUB_SHA:.github/scripts/assert-native-set.mjs" > "$judge" 2>/dev/null; then
+ cp .github/scripts/assert-native-set.mjs "$judge" 2>/dev/null || true
+ fi
selector="${RUNNER_TEMP:-/tmp}/select-native-config-prebuild.mjs"
if ! git show "$GITHUB_SHA:.github/scripts/select-native-config-prebuild.mjs" > "$selector" 2>/dev/null; then
cp .github/scripts/select-native-config-prebuild.mjs "$selector" 2>/dev/null || true
fi
if [ ! -s "$selector" ]; then
- degrade_or_fail "native-config prebuild selector is missing at $GITHUB_SHA and in the release checkout" "0/8"
+ judge_staging "native-config prebuild selector is missing at $GITHUB_SHA and in the release checkout"
fi
nc_err="${RUNNER_TEMP:-/tmp}/native-config-select.err"
if ! selection=$(node "$selector" 2>"$nc_err"); then
reason=$(tr '\n' ' ' < "$nc_err" | sed 's/ *$//')
- degrade_or_fail "${reason:-could not select a native-config prebuild run}" "0/8"
+ judge_staging "${reason:-could not select a native-config prebuild run}"
fi
# Assert the WHOLE shape, on ONE line. Testing for a tab anywhere is
# not enough: a stray line ahead of the real answer still contains a
@@ -379,22 +381,18 @@ jobs:
selection_shape='^[0-9]+'$'\t''[0-9a-f]{7,40}$'
if [[ ! $selection =~ $selection_shape ]]; then
flattened=$(printf '%s' "$selection" | tr '\n' ' ')
- degrade_or_fail "native-config prebuild selector returned an unusable answer: $flattened" "0/8"
+ judge_staging "native-config prebuild selector returned an unusable answer: $flattened"
fi
run_id="${selection%%$'\t'*}"
head_sha="${selection##*$'\t'}"
if ! download_bindings "$run_id"; then
- degrade_or_fail "could not download native-config-bindings-all from run $run_id after 3 attempts" "0/8"
+ judge_staging "could not download native-config-bindings-all from run $run_id after 3 attempts"
fi
find /tmp/nc-bindings -name '*.node' -exec cp -f {} packages/native-config/ \;
count=$(find packages/native-config -maxdepth 1 -name '*.node' | wc -l | tr -d ' ')
echo "staged $count native-config prebuilt binaries from run $run_id (commit $head_sha)"
- if [ "$count" -lt 8 ]; then
- degrade_or_fail "staged only $count/8 native-config binaries" "$count/8"
- fi
- require_windows_targets "staged $count/8 native-config binaries from run $run_id"
- summarize "$count/8 from run $run_id (commit $head_sha)"
+ judge_staging "staged $count native-config binaries from run $run_id (commit $head_sha)"
# The workspace build produces native-config's host `.node` via `napi
# build` (turbo dep of the cli build), which needs a Rust toolchain —
@@ -433,12 +431,18 @@ jobs:
done
echo "All fixed-group package.json files + both skill bundles' metadata.version now at ${VERSION} (in-memory only)."
- # Same two-filter sequencing as the mac job: app must build before cli's
- # build:assets copies app/dist into cli/dist/public.
- name: Build workspace (produces packages/cli/dist for extraResources)
run: |
- pnpm exec turbo run build --filter=@inkeep/open-knowledge-app
- pnpm exec turbo run build --filter=@inkeep/open-knowledge
+ pnpm exec turbo run build --filter=@inkeep/open-knowledge --cache=local:,remote:
+
+ - name: Assert the native-config binary set
+ env:
+ NATIVE_SET_PLATFORMS: ${{ steps.stage.outputs.platforms }}
+ run: |
+ set -euo pipefail
+ git cat-file -e "$GITHUB_SHA^{commit}" 2>/dev/null || git fetch --no-tags --depth=1 origin "$GITHUB_SHA"
+ git show "$GITHUB_SHA:.github/scripts/assert-native-set.mjs" > "$RUNNER_TEMP/assert-native-set.mjs"
+ node "$RUNNER_TEMP/assert-native-set.mjs" platforms "$NATIVE_SET_PLATFORMS"
# Hand the platform-neutral build products to the Windows/Linux packaging
# jobs: the full bundled CLI tree + core/server dist + the native-config
@@ -559,14 +563,6 @@ jobs:
restore-keys: |
${{ runner.os }}-ok-pnpm-store-
- - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
- with:
- path: .turbo
- key: ${{ runner.os }}-turbo-desktop-release-${{ hashFiles('pnpm-lock.yaml') }}
- restore-keys: |
- ${{ runner.os }}-turbo-desktop-release-
- ${{ runner.os }}-turbo-desktop-
-
- name: Install dependencies
env:
# Rebuild native modules against Electron's Node ABI — same as
@@ -595,21 +591,16 @@ jobs:
done
echo "All fixed-group package.json files + both skill bundles' metadata.version now at ${VERSION} (in-memory only)."
- # electron-builder.yml's `extraResources` rule copies from
- # `packages/cli/dist/public/`, which the CLI's `build:assets` populates
- # via `cp -r ../app/dist dist/public`. The CLI does not declare the
- # app as a workspace dep (app is private, and the CLI ships the
- # compiled bundle — not a package reference), so turbo's `^build`
- # runs them in parallel by default. Without explicit sequencing, cli's
- # `build:assets` races app's vite build and can fail (no `app/dist`
- # yet) or copy stale content. Use turbo's `--filter=@inkeep/...`
- # which DOES respect the `^build` graph (so server + core build
- # before app), and run the two filters in sequence to enforce
- # app → cli ordering.
- name: Build workspace (produces packages/cli/dist/public for extraResources)
run: |
- pnpm exec turbo run build --filter=@inkeep/open-knowledge-app
- pnpm exec turbo run build --filter=@inkeep/open-knowledge
+ pnpm exec turbo run build --filter=@inkeep/open-knowledge --cache=local:,remote:
+
+ - name: Assert the native-config binary set
+ run: |
+ set -euo pipefail
+ git cat-file -e "$GITHUB_SHA^{commit}" 2>/dev/null || git fetch --no-tags --depth=1 origin "$GITHUB_SHA"
+ git show "$GITHUB_SHA:.github/scripts/assert-native-set.mjs" > "$RUNNER_TEMP/assert-native-set.mjs"
+ node "$RUNNER_TEMP/assert-native-set.mjs" host
- name: Detect signing mode
id: signmode
@@ -1030,6 +1021,7 @@ jobs:
build-windows:
needs: prepare
+ if: contains(needs.prepare.outputs.platforms, 'windows')
strategy:
fail-fast: false
matrix:
@@ -1359,6 +1351,7 @@ jobs:
# installs the arm64 prebuilds directly.
build-linux:
needs: prepare
+ if: contains(needs.prepare.outputs.platforms, 'linux')
runs-on: ${{ matrix.runner }}
timeout-minutes: 45
env:
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 0a81d597a..6220b5bab 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -193,20 +193,15 @@ jobs:
run: pnpm install --frozen-lockfile
- name: Stage native-config prebuilt binaries
+ id: stage
env:
GH_TOKEN: ${{ github.token }}
- IS_STABLE: ${{ github.event_name == 'repository_dispatch' }}
+ SERVES: mac,windows,linux
+ REQUIRES: mac,windows,linux
run: |
summarize() {
echo "Staged native-config binaries: $1" >> "$GITHUB_STEP_SUMMARY"
}
- require_windows_targets() {
- for required in native-config.win32-x64-msvc.node native-config.win32-arm64-msvc.node; do
- if [ -f "packages/native-config/$required" ]; then continue; fi
- echo "::error::$1; $required was not staged, and Windows removal reads process identity through the native addon, so this cut cannot publish. If no prebuild run matches this commit's packages/native-config tree, re-run native-config-prebuild.yml on an ancestor of this commit; if staging failed for another reason, re-run this workflow. Either way resume per RELEASES.md 'Native addon staging (Windows is mandatory)'."
- exit 1
- done
- }
download_bindings() {
for attempt in 1 2 3; do
rm -rf /tmp/nc-bindings
@@ -217,16 +212,15 @@ jobs:
done
return 1
}
- degrade_or_fail() {
- # $1: human-readable reason, $2: staged-count label for the summary
- summarize "$2 — $1"
- require_windows_targets "$1"
- if [ "$IS_STABLE" = "true" ]; then
- echo "::error::$1; refusing to cut a stable @latest release with an incomplete native-config binary set"
+ judge_staging() {
+ summarize "$1"
+ if [ ! -s "$judge" ]; then
+ echo "::error::the native-set judge is missing at $GITHUB_SHA and in the release checkout; refusing this cut"
exit 1
fi
- echo "::warning::$1; both Windows binaries were staged, so only other targets are missing"
- exit 0
+ node "$judge" staged --serves "$SERVES" --requires "$REQUIRES" --reason "$1" \
+ --recovery "If no prebuild run matches this commit's packages/native-config tree, re-run native-config-prebuild.yml on an ancestor of this commit; if staging failed for another reason, re-run this workflow. Either way resume per RELEASES.md 'Native addon staging'."
+ exit $?
}
# Which prebuild run may be staged is release policy shared with the
@@ -246,18 +240,23 @@ jobs:
# checked-out copy. Pairing the two is what lets a re-fire on a stale
# tag run CURRENT release machinery rather than whatever was frozen in
# that tag, which is the only way re-firing a blocked release can ever
- # clear it. fetch-depth:0 in checkout has $GITHUB_SHA.
+ # clear it. fetch-depth:0 in checkout has $GITHUB_SHA. The native-set
+ # judge that decides what staging may package comes the same way.
+ judge="${RUNNER_TEMP:-/tmp}/assert-native-set.mjs"
+ if ! git show "$GITHUB_SHA:.github/scripts/assert-native-set.mjs" > "$judge" 2>/dev/null; then
+ cp .github/scripts/assert-native-set.mjs "$judge" 2>/dev/null || true
+ fi
selector="${RUNNER_TEMP:-/tmp}/select-native-config-prebuild.mjs"
if ! git show "$GITHUB_SHA:.github/scripts/select-native-config-prebuild.mjs" > "$selector" 2>/dev/null; then
cp .github/scripts/select-native-config-prebuild.mjs "$selector" 2>/dev/null || true
fi
if [ ! -s "$selector" ]; then
- degrade_or_fail "native-config prebuild selector is missing at $GITHUB_SHA and in the release checkout" "0/8"
+ judge_staging "native-config prebuild selector is missing at $GITHUB_SHA and in the release checkout"
fi
nc_err="${RUNNER_TEMP:-/tmp}/native-config-select.err"
if ! selection=$(node "$selector" 2>"$nc_err"); then
reason=$(tr '\n' ' ' < "$nc_err" | sed 's/ *$//')
- degrade_or_fail "${reason:-could not select a native-config prebuild run}" "0/8"
+ judge_staging "${reason:-could not select a native-config prebuild run}"
fi
# Assert the WHOLE shape, on ONE line. Testing for a tab anywhere is
# not enough: a stray line ahead of the real answer still contains a
@@ -269,25 +268,21 @@ jobs:
selection_shape='^[0-9]+'$'\t''[0-9a-f]{7,40}$'
if [[ ! $selection =~ $selection_shape ]]; then
flattened=$(printf '%s' "$selection" | tr '\n' ' ')
- degrade_or_fail "native-config prebuild selector returned an unusable answer: $flattened" "0/8"
+ judge_staging "native-config prebuild selector returned an unusable answer: $flattened"
fi
run_id="${selection%%$'\t'*}"
head_sha="${selection##*$'\t'}"
if ! download_bindings "$run_id"; then
- degrade_or_fail "could not download native-config-bindings-all from run $run_id after 3 attempts" "0/8"
+ judge_staging "could not download native-config-bindings-all from run $run_id after 3 attempts"
fi
find /tmp/nc-bindings -name '*.node' -exec cp -f {} packages/native-config/ \;
count=$(find packages/native-config -maxdepth 1 -name '*.node' | wc -l | tr -d ' ')
echo "staged $count native-config prebuilt binaries from run $run_id (commit $head_sha)"
- if [ "$count" -lt 8 ]; then
- degrade_or_fail "staged only $count/8 native-config binaries" "$count/8"
- fi
- require_windows_targets "staged $count/8 native-config binaries from run $run_id"
- summarize "$count/8 from run $run_id (commit $head_sha)"
+ judge_staging "staged $count native-config binaries from run $run_id (commit $head_sha)"
- # `pnpm run build` builds the native-config addon's host `.node` via
- # `napi build` (turbo dep of the cli build), which needs a Rust toolchain.
+ # The workspace build produces native-config's host `.node` via `napi
+ # build` (turbo dep of the cli build), which needs a Rust toolchain.
# Pin it explicitly rather than relying on whatever `ubuntu-latest`
# preinstalls, so an image change can't silently break the whole publish at
# the unguarded cargo invocation. Mirrors native-config-prebuild.yml.
@@ -300,11 +295,21 @@ jobs:
# in turn fires the cli's `prepublishOnly` (-> `pnpm run build`). The
# cli's own build chain includes `cp -r ../app/dist dist/public`
# which silently fails when the app hasn't been built first. Run a
- # top-level `pnpm run build` (turbo orchestrates the dep order:
+ # top-level turbo build (turbo orchestrates the dep order:
# app -> cli) so every package's dist/ exists before the publish
# step runs.
- name: Build packages
- run: pnpm run build
+ run: |
+ pnpm exec turbo run build --cache=local:,remote:
+
+ - name: Assert the native-config binary set
+ env:
+ NATIVE_SET_PLATFORMS: ${{ steps.stage.outputs.platforms }}
+ run: |
+ set -euo pipefail
+ git cat-file -e "$GITHUB_SHA^{commit}" 2>/dev/null || git fetch --no-tags --depth=1 origin "$GITHUB_SHA"
+ git show "$GITHUB_SHA:.github/scripts/assert-native-set.mjs" > "$RUNNER_TEMP/assert-native-set.mjs"
+ node "$RUNNER_TEMP/assert-native-set.mjs" platforms "$NATIVE_SET_PLATFORMS"
# --- BETA PATH (push + workflow_dispatch) ---
diff --git a/packages/cli/package.json b/packages/cli/package.json
index e81d76183..3bb9019d4 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -45,7 +45,7 @@
"build:skill-asset": "tsx scripts/build-skill-assets.ts",
"build:notices": "mkdir -p dist && cp ../../THIRD_PARTY_NOTICES.md dist/THIRD_PARTY_NOTICES.md",
"build:license": "mkdir -p dist && cp ../../LICENSE dist/LICENSE",
- "build:native": "mkdir -p dist/native && cp ../native-config/index.js ../native-config/index.d.ts ../native-config/package.json dist/native/ && (cp ../native-config/*.node dist/native/ 2>/dev/null || true)",
+ "build:native": "mkdir -p dist/native && cp ../native-config/index.js ../native-config/index.d.ts ../native-config/package.json ../native-config/*.node dist/native/",
"build:schema": "node --import tsx --conditions=development scripts/build-config-schema.mjs",
"build:assets": "pnpm run build:app && pnpm run build:skill-asset && pnpm run build:notices && pnpm run build:license && pnpm run build:native && pnpm run build:schema",
"build": "pnpm run build:cli && pnpm run build:assets",
diff --git a/packages/cli/scripts/build-native.test.ts b/packages/cli/scripts/build-native.test.ts
new file mode 100644
index 000000000..35d4435e7
--- /dev/null
+++ b/packages/cli/scripts/build-native.test.ts
@@ -0,0 +1,55 @@
+import { spawnSync } from 'node:child_process';
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readdirSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, describe, expect, test } from 'vitest';
+
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const BUILD_NATIVE: string = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'))
+ .scripts['build:native'];
+const LOADER = ['index.d.ts', 'index.js', 'package.json'];
+
+const scratches: string[] = [];
+
+afterEach(() => {
+ for (const dir of scratches.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+function runBuildNative(binaries: string[]) {
+ const root = mkdtempSync(join(tmpdir(), 'ok-cli-build-native-'));
+ scratches.push(root);
+ const nativeConfig = join(root, 'native-config');
+ const cli = join(root, 'cli');
+ mkdirSync(nativeConfig);
+ mkdirSync(cli);
+ for (const file of [...LOADER, ...binaries]) writeFileSync(join(nativeConfig, file), file);
+ const result = spawnSync('sh', ['-c', BUILD_NATIVE], { cwd: cli, encoding: 'utf8' });
+ const dist = join(cli, 'dist', 'native');
+ return { status: result.status, copied: existsSync(dist) ? readdirSync(dist).sort() : [] };
+}
+
+describe.skipIf(process.platform === 'win32')(
+ 'build:native, which pnpm runs through sh on POSIX hosts',
+ () => {
+ test('fails when native-config holds no binary, instead of shipping a CLI without its addon', () => {
+ expect(runBuildNative([]).status).not.toBe(0);
+ });
+
+ test('copies the loader and every binary native-config holds', () => {
+ const binaries = ['native-config.darwin-arm64.node', 'native-config.win32-x64-msvc.node'];
+ expect(runBuildNative(binaries)).toEqual({
+ status: 0,
+ copied: [...LOADER, ...binaries].sort(),
+ });
+ });
+ },
+);