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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/agent-studio-electron-45.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@sapiom/harness-desktop": minor
---

Agent Studio runs on Electron 45; it requires macOS 13 or later.
15 changes: 7 additions & 8 deletions .github/workflows/desktop-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -242,19 +242,18 @@ jobs:
cache: "pnpm"

- name: Use Python 3.11 (node-gyp needs distutils)
# electron-builder rebuilds node-pty from source where no matching
# prebuilt exists (macOS/arm64, Windows). Its bundled node-gyp@9 imports
# `distutils`, which Python 3.12+ removed (PEP 632) — and the macOS/
# Windows runners default to 3.12+. Pinning 3.11 (which still ships
# distutils) fixes the rebuild without upgrading node-gyp. No-op on
# Linux, which uses node-pty's prebuilt binary and never compiles.
# Keep Python 3.11 until a release run validates the runners' default Python
# with @electron/rebuild 4 and node-gyp 12. node-gyp 9 requires distutils,
# which Python 3.12+ omits (PEP 632). node-pty needs a source rebuild wherever
# no matching prebuild is used; it ships no Linux prebuilds.
uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
with:
python-version: "3.11"

- name: Install dependencies
# onlyBuiltDependencies (pnpm-workspace.yaml) lets electron/node-pty/
# esbuild run their postinstall — electron downloads its binary here.
# onlyBuiltDependencies (pnpm-workspace.yaml) lets esbuild and node-pty
# run their install scripts. electron has none: it fetches its binary on
# first launch, and packaging downloads its own copy.
run: pnpm install --frozen-lockfile

- name: Build harness + desktop (topological)
Expand Down
44 changes: 31 additions & 13 deletions packages/harness-desktop/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,14 @@ touching this package, and how to tell whether a change actually works on the OS

| OS | Role | Artifacts | node-pty |
| --- | --- | --- | --- |
| Linux | dev/proof platform | `AppImage`, `deb` | **prebuilt binary — never compiles** |
| **macOS** | **required deliverable** (signed + notarized) | `dmg`, `zip` (arm64 today) | compiled from source |
| Linux | dev/proof platform | `AppImage`, `deb` | compiled from source (node-pty ships no Linux prebuild) |
| **macOS** | **required deliverable** (signed + notarized), macOS 13+ | `dmg`, `zip` (arm64 today) | compiled from source |
| Windows | in scope, lower priority | `nsis` `.exe` | compiled from source |

> **A green Linux build proves almost nothing about the other two.** Linux uses node-pty's prebuilt
> binary, so node-gyp never runs — which is exactly why Linux passed through every CI failure that
> macOS and Windows hit. Don't infer cross-platform health from it.
> **A green Linux build proves almost nothing about the other two.** Linux compiles node-pty with
> the system gcc and none of the macOS/Windows toolchain quirks below (Python, Visual Studio), which
> is why Linux passed through every CI failure that macOS and Windows hit. Don't infer
> cross-platform health from it.

## Main-process code that survives all three OSes

Expand Down Expand Up @@ -101,6 +102,12 @@ plain Node with no asar support, so their whole import tree must exist on disk.
recompiles node-pty against the Electron ABI **on the packaging OS** — there is no cross-compiling
here, each OS builds on its own runner.

**`pack.mjs` writes the root `packageManager` into the deploy dir's `package.json`.** electron-builder
26 picks its node_modules collector from that field, then the lockfile, then the environment
(`npm_config_user_agent`, `npm_execpath`), else npm, and the deploy dir has no lockfile. Built the CI
way, that resolved to npm, whose collection left esbuild's platform binary out of the package, and
the `deploy-bundle` smoke check failed. The field makes every run collect with pnpm.

**A dependency that execs a sidecar binary needs more than `asarUnpack`.** Unpacking puts the file on
disk but leaves every path `require.resolve` reports pointing at `app.asar`, and `spawn` — unlike
`fs` — is not patched, so it fails with `ENOTDIR`. This shipped in 0.1.0: deploying a workflow died
Expand All @@ -126,8 +133,15 @@ smoke check starts two real runtimes, creates independent sessions, and requires
- Canonicalize the tmpdir or electron-builder fails with `ENOENT .pnpm/node_modules/@sapiom/…`: it
realpaths the dir, and a non-canonical base leaves the relative symlinks' `../` chains one level
short.
- **Python 3.12+ removed `distutils`** (PEP 632) and node-gyp@9 imports it → the rebuild dies. CI
pins Python 3.11.
- **Python 3.12+ removed `distutils`** (PEP 632) and node-gyp@9 imported it, so the rebuild died. CI
pins Python 3.11. The rebuild now runs node-gyp 12 (via app-builder-lib's `@electron/rebuild` 4);
keep the pin until a release run proves the default Python works.
- **The build runs on macOS 13 or later only** (Electron 44+). `mac.minimumSystemVersion` sets the
bundle's `LSMinimumSystemVersion`, and `pack.mjs --mac` stamps the matching Darwin floor
(`minimumSystemVersion: 22.0.0`) into `latest-mac.yml`/`beta-mac.yml`. That stamp is what stops an
installed app on macOS 11/12 from auto-updating into a build it cannot launch: electron-updater
reads the manifest, never the plist (`src/main/mac-minimum.ts`). Raise both together with the next
Electron floor; `electron-version.test.ts` pins them.
- **Only arm64 is built today.** `macos-14` is Apple Silicon and electron-builder defaults to the
host arch, so **Intel Macs get no artifact**. Add an `x64`/universal target before GA if Intel users
are in scope.
Expand Down Expand Up @@ -163,9 +177,9 @@ smoke check starts two real runtimes, creates independent sessions, and requires
`D:\…\harness-desktop\C:\Users\…` (`scripts/pack.mjs:35`).
- **Pinned to `windows-2022`.** `windows-latest` rolled to a Visual Studio 18 image that node-gyp's
VS detection reports as "unknown version undefined" → no usable compiler.
- The `@electron/rebuild: ^3.7.0` override in `pnpm-workspace.yaml` is what gets a VS2022-aware
node-gyp. **Do not instead override `node-gyp` itself** — that hung the rebuild on *every*
platform.
- There is no `@electron/rebuild` override any more: app-builder-lib 26 depends on
`@electron/rebuild` 4, whose node-gyp 12 detects VS2022. **Do not override `node-gyp` itself**:
that hung the rebuild on *every* platform.
- **`cmd.exe` does not strip single quotes.** A script doing `echo '{"type":"module"}' > pkg.json`
writes literal quotes → invalid JSON → the packaged app dies at launch with
`ERR_INVALID_PACKAGE_CONFIG`. Use `node -e "require('fs').writeFileSync(…)"`. This applies to
Expand All @@ -179,6 +193,8 @@ smoke check starts two real runtimes, creates independent sessions, and requires
`./sapiom-*.AppImage --appimage-extract 'resources/app.asar'` then `grep -a` it. The packaged
bundle is the source of truth — not your `dist/`.
- Node 26 on a dev box breaks Electron's binary extraction and `electron-rebuild`; CI uses Node 22.
Electron 45 itself needs Node >= 22.12 to install (`engines.node`).
- Packaging locally needs `make` and a C++ compiler, since node-pty compiles here.

## CI

Expand Down Expand Up @@ -253,9 +269,11 @@ Things that will bite you:
`latest-mac.yml` is only written when a zip target exists. It also refuses to apply an unsigned
update — so auto-update on macOS depends on the Developer ID cert, not just on this code.
- **The `publish:` block in `electron-builder.yml` is load-bearing even though we never publish from
electron-builder** (`pack.mjs` passes `--publish never` so it can't race the release job). Without a
publish provider, no `latest*.yml` is generated and no `resources/app-update.yml` is baked in — the
app then runs perfectly and never updates. The `update-config` smoke check exists for that, and it
electron-builder** (`pack.mjs` passes `--publish never` so it can't race the release job, and
accepts only `--linux`/`--mac`/`--win` plus `-c.<key>` passthrough args, since a mac build that
publishes itself or picks its platform another way would upload or keep `latest-mac.yml`
unstamped). Without a publish provider, no `latest*.yml` is generated and no
`resources/app-update.yml` is baked in — the app then runs perfectly and never updates. The `update-config` smoke check exists for that, and it
also cross-checks the *baked* channel against the one the app resolves at runtime.
- **Don't derive the channel in a workflow.** `pack.mjs` imports `resolveUpdateChannel` from the built
`dist/` and passes the flag itself, so the release workflow, the PR smoke job and a local
Expand Down
5 changes: 4 additions & 1 deletion packages/harness-desktop/electron-builder.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ copyright: Copyright © Sapiom
# Pinned because packaging runs against a `pnpm deploy --prod` dir that has no
# `electron` devDep for electron-builder to infer the version from. Keep in sync
# with the `electron` devDependency.
electronVersion: 33.4.11
electronVersion: 45.2.1

# Custom URL scheme for web→desktop deep links (the dashboard's "Open in Studio").
# Populates macOS CFBundleURLTypes (Info.plist) and the Linux .desktop MimeType.
Expand Down Expand Up @@ -100,6 +100,9 @@ mac:
# size as its neighbours in the Dock. A full-bleed tile (correct on Linux and
# Windows) reads as conspicuously oversized next to system apps.
icon: assets/icon-mac.png
# Electron 44+ does not run on macOS 12 or older. This sets LSMinimumSystemVersion;
# pack.mjs stamps the matching floor into the update manifest (src/main/mac-minimum.ts).
minimumSystemVersion: "13.0"
hardenedRuntime: true
gatekeeperAssess: false
entitlements: assets/entitlements.mac.plist
Expand Down
13 changes: 6 additions & 7 deletions packages/harness-desktop/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -22,20 +22,19 @@
"dependencies": {
"@sapiom/harness": "workspace:^",
"@sapiom/opencode": "workspace:^",
"electron-updater": "^6.8.9",
"electron-updater": "^6.8.11",
"node-pty": "^1.1.0",
"npm": "^10.9.0"
},
"devDependencies": {
"@electron/notarize": "^2.5.0",
"@electron/rebuild": "^3.7.0",
"@types/node": "^20.11.30",
"electron": "^33.0.0",
"electron-builder": "^25.1.8",
"@electron/rebuild": "^4.2.1",
"@types/node": "^24.9.0",
"electron": "45.2.1",
"electron-builder": "^26.18.0",
"typescript": "^5.4.2",
"vitest": "^3.0.0"
},
"engines": {
"node": ">=20.0.0"
"node": ">=22.12.0"
}
}
25 changes: 25 additions & 0 deletions packages/harness-desktop/scripts/pack-args.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
// Validates pack.mjs's argv: [platform flag] [...electron-builder args].
//
// Both lists are allowlists. electron-builder's yargs also accepts other
// spellings of the platform (`--macos`, `-m`, `-o`) and of the publish flag
// (`-p`, grouped short options, repeats). Any of them would let a mac build skip
// the update-manifest stamp, or upload latest-mac.yml before it is stamped
// (src/main/mac-minimum.ts), so only the spellings pack.mjs understands get through.
export const PLATFORM_FLAGS = ["--linux", "--mac", "--win"];
const CONFIG_OVERRIDE = /^(?:-c|--config)\.[A-Za-z]/;

export function parsePackArgs(argv, hostPlatformFlag) {
// Empty strings dropped: a shell passing an unset flag as "" would otherwise
// reach electron-builder as a bogus empty argument.
const [platform = hostPlatformFlag, ...passthrough] = argv.filter((arg) => arg.length > 0);
if (!PLATFORM_FLAGS.includes(platform)) {
throw new Error(`pack.mjs: the platform must be one of ${PLATFORM_FLAGS.join(", ")} (got ${platform})`);
}
const rejected = passthrough.filter((arg) => !CONFIG_OVERRIDE.test(arg));
if (rejected.length > 0) {
throw new Error(
`pack.mjs: only -c.<key> overrides pass through to electron-builder (got ${rejected.join(" ")})`,
);
}
return { platform, passthrough };
}
38 changes: 30 additions & 8 deletions packages/harness-desktop/scripts/pack.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,16 @@
// electron-builder there, writing artifacts back to <pkg>/release.
//
// Usage: node scripts/pack.mjs [--linux|--mac|--win] [...electron-builder args]
// (defaults to the HOST platform; any further args pass through, e.g.
// -c.mac.notarize=true)
// (defaults to the HOST platform; further args must be -c.<key> overrides,
// e.g. -c.mac.notarize=true, and pass through; see pack-args.mjs)
import { execFileSync } from "node:child_process";
import { cpSync, mkdirSync, readFileSync, realpathSync, rmSync } from "node:fs";
import { cpSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
import * as os from "node:os";

import { assertHarnessVersion } from "./harness-version.mjs";
import { parsePackArgs } from "./pack-args.mjs";

const pkgDir = dirname(dirname(fileURLToPath(import.meta.url))); // packages/harness-desktop
const repoRoot = dirname(dirname(pkgDir)); // sapiom-js
Expand All @@ -31,14 +32,11 @@ const outputDir = join(pkgDir, "release");
* then looked for a `release/mac-arm64/Sapiom.app` nothing had built.
*/
const HOST_PLATFORM_FLAG = { darwin: "--mac", win32: "--win" }[process.platform] ?? "--linux";
const platform = process.argv[2] ?? HOST_PLATFORM_FLAG;
// Anything after the platform flag goes straight to electron-builder. Signing
// Config overrides after the platform flag go straight to electron-builder. Signing
// and notarization are switched on this way (`-c.mac.notarize=true`) rather than
// hardcoded in electron-builder.yml, so a build without credentials still
// succeeds unsigned instead of failing.
// Empty strings filtered out: a shell passing an unset flag as "" would
// otherwise reach electron-builder as a bogus empty argument.
const passthrough = process.argv.slice(3).filter((arg) => arg.length > 0);
const { platform, passthrough } = parsePackArgs(process.argv.slice(2), HOST_PLATFORM_FLAG);
const isWindows = process.platform === "win32";

// The update channel this artifact publishes to, derived HERE rather than by each
Expand All @@ -64,6 +62,11 @@ const { resolveUpdateChannel } = await import(
pathToFileURL(join(pkgDir, "dist", "main", "update-policy.js")).href
);
const { channel } = resolveUpdateChannel(version, {});

const macMinimum =
platform === "--mac"
? await import(pathToFileURL(join(pkgDir, "dist", "main", "mac-minimum.js")).href)
: null;
// An explicit caller flag still wins — the passthrough args land after ours.
const channelFlag = passthrough.some((arg) => arg.startsWith("-c.publish.channel"))
? []
Expand Down Expand Up @@ -110,6 +113,15 @@ assertHarnessVersion(
"deployed desktop bundle",
);

// Pin electron-builder 26's collector to pnpm: without lockfile metadata,
// detection depends on the invoking environment and defaults to npm.
// npm's walk of this pnpm layout can omit esbuild's platform binary,
// breaking deploy bundling (the `deploy-bundle` smoke check).
const deployPkgPath = join(deployDir, "package.json");
const deployPkg = JSON.parse(readFileSync(deployPkgPath, "utf8"));
deployPkg.packageManager = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8")).packageManager;
writeFileSync(deployPkgPath, `${JSON.stringify(deployPkg, null, 2)}\n`);

// `pnpm deploy` honors .gitignore, which excludes dist/ + release/. Copy the
// built app output, the builder config, and assets into the deploy dir.
cpSync(join(pkgDir, "dist"), join(deployDir, "dist"), { recursive: true });
Expand Down Expand Up @@ -153,4 +165,14 @@ run(
deployDir,
);

// electron-builder writes the macOS floor only into Info.plist. Installed apps read
// it from the update manifest, so stamp it there or Macs below the floor
// auto-update into a build they cannot launch (src/main/mac-minimum.ts). Throws
// when no mac manifest exists, failing the build instead of shipping one unstamped.
if (macMinimum) {
console.log(
`[pack] stamped minimumSystemVersion into ${macMinimum.stampMacManifests(outputDir).join(", ")}`,
);
}

console.log(`[pack] done → ${outputDir}`);
89 changes: 89 additions & 0 deletions packages/harness-desktop/src/main/dependency-pins.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
/**
* Dependency floors for the packaged runtime. A lockfile re-resolve, a merge or a
* revert can quietly bring back an older Electron or builder chain; these read
* the three files that decide what ships. Floors, not equalities, so a later
* upgrade stays green.
*/
import { readFileSync } from "node:fs";
import { describe, expect, it } from "vitest";

const read = (relative: string): string => readFileSync(new URL(relative, import.meta.url), "utf8");
const pkg = JSON.parse(read("../../package.json")) as {
dependencies?: Record<string, string>;
devDependencies: Record<string, string>;
engines: { node: string };
};
const lockfile = read("../../../../pnpm-lock.yaml");
const workspace = read("../../../../pnpm-workspace.yaml");

type Version = [number, number, number];

/** The x.y.z a version or a `^`/`~`/`>=` range starts from. */
function floorOf(spec: string): Version {
const match = /^(?:\^|~|>=)?\s*(\d+)\.(\d+)\.(\d+)/.exec(spec);
if (!match) throw new Error(`no version floor in "${spec}"`);
return [Number(match[1]), Number(match[2]), Number(match[3])];
}

function atLeast(actual: Version, minimum: string): boolean {
const min = floorOf(minimum);
for (let i = 0; i < 3; i += 1) {
if (actual[i] !== min[i]) return actual[i] > min[i];
}
return true;
}

/** Every version of `name` in the lockfile's packages and snapshots sections. */
function lockedVersions(name: string): string[] {
const escaped = name.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
const key = new RegExp(`^ '?${escaped}@(\\d+\\.\\d+\\.\\d+)[^:]*'?:$`, "gm");
return [...new Set([...lockfile.matchAll(key)].map((match) => match[1]))];
}

const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };

describe("package.json floors", () => {
it("pins electron exactly, at 45.2.1 or later", () => {
expect(pkg.devDependencies.electron).toMatch(/^\d+\.\d+\.\d+$/);
expect(atLeast(floorOf(pkg.devDependencies.electron), "45.2.1")).toBe(true);
});

it.each([
["electron-builder", "26.18.0"],
["electron-updater", "6.8.11"],
["@electron/rebuild", "4.2.1"],
["@types/node", "24.0.0"],
])("declares %s from %s", (name, minimum) => {
expect(allDeps[name], name).toBeDefined();
expect(atLeast(floorOf(allDeps[name]), minimum)).toBe(true);
});

it("requires Node 22.12 or later, Electron's own floor", () => {
expect(atLeast(floorOf(pkg.engines.node), "22.12.0")).toBe(true);
});

it("drops @electron/notarize", () => {
expect(allDeps["@electron/notarize"]).toBeUndefined();
});
});

describe("pnpm-lock.yaml floors", () => {
it("locks electron at exactly the devDependency version", () => {
expect(lockedVersions("electron")).toEqual([pkg.devDependencies.electron]);
});

it.each([
["app-builder-lib", "26.18.0"],
["@electron/rebuild", "4.0.0"],
])("locks %s at %s or later only", (name, minimum) => {
const versions = lockedVersions(name);
expect(versions.length, name).toBeGreaterThan(0);
for (const version of versions) expect(atLeast(floorOf(version), minimum), `${name}@${version}`).toBe(true);
});
});

describe("pnpm-workspace.yaml", () => {
it("has no @electron/rebuild override, which would pin app-builder-lib's own below v4", () => {
expect(workspace).not.toMatch(/^\s+["']?@electron\/rebuild["']?(@[^:]*)?\s*:/m);
});
});
Loading
Loading