Skip to content

A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.

TypeScript

ci(windows): build the app channel addon and test it on Windows

Marcelitofab7bfa263f4
diff --git a/.github/workflows/windows.yml b/.github/workflows/windows.yml
index 01d039c..ce18c3f 100644
--- a/.github/workflows/windows.yml
+++ b/.github/workflows/windows.yml
@@ -47,3 +47,54 @@ jobs:
working-directory: apps/desktop/src-tauri
run: cargo test --locked --lib
+ app-channel:
+ name: Native app channel
+ runs-on: windows-latest
+ steps:
+ - uses: actions/checkout@v7
+ - uses: pnpm/action-setup@v4
+ - uses: actions/setup-node@v6
+ with:
+ node-version: 24
+ cache: pnpm
+ # gentle-pi's Windows postinstall requires local Go 1.25.10 or newer.
+ - uses: actions/setup-go@v5
+ with:
+ go-version: '1.25.x'
+ cache: false
+ - run: pnpm install --frozen-lockfile
+
+ # The build takes an explicit cl.exe path and needs the SDK's INCLUDE and LIB.
+ - uses: ilammy/[email protected]
+ with:
+ arch: x64
+
+ # Provision inputs here, not in the build script; match the running Node exactly.
+ - name: Build app-channel addon
+ shell: pwsh
+ run: |
+ $ErrorActionPreference = 'Stop'
+ $version = node -p process.version
+ $inputs = Join-Path $env:RUNNER_TEMP 'node-addon-inputs'
+ New-Item -ItemType Directory -Force -Path $inputs | Out-Null
+ $release = "https://nodejs.org/download/release/$version"
+ Invoke-WebRequest "$release/node-$version-headers.tar.gz" -OutFile "$inputs/headers.tar.gz"
+ Invoke-WebRequest "$release/win-x64/node.lib" -OutFile "$inputs/node.lib"
+ # Both downloads must match the release's published SHA-256 sums.
+ $sums = (Invoke-WebRequest "$release/SHASUMS256.txt").Content -split "`n"
+ foreach ($pair in @(@("node-$version-headers.tar.gz", 'headers.tar.gz'), @('win-x64/node.lib', 'node.lib'))) {
+ $line = $sums | Where-Object { $_ -match "^[0-9a-f]{64}\s+$([regex]::Escape($pair[0]))$" }
+ if (-not $line) { throw "No published checksum for $($pair[0])" }
+ $actual = (Get-FileHash -Algorithm SHA256 (Join-Path $inputs $pair[1])).Hash.ToLowerInvariant()
+ if ($actual -ne ($line -split '\s+')[0]) { throw "Checksum mismatch for $($pair[0])" }
+ }
+ tar -xf "$inputs/headers.tar.gz" -C $inputs
+ if ($LASTEXITCODE -ne 0) { throw 'Node header extraction failed' }
+ $compiler = (Get-Command cl.exe).Source
+ pnpm --filter @gentle-dot/daemon run build:windows-stop -- --compiler "$compiler" --headers "$inputs/node-$version/include/node" --node-lib "$inputs/node.lib"
+ if ($LASTEXITCODE -ne 0) { throw 'Native addon build failed' }
+
+ # These portable adapter tests and real-addon refusal tests stay together.
+ - name: App-channel tests
+ run: pnpm exec vitest run packages/daemon/test/windows-app-channel.test.ts packages/daemon/test/app-channel-platform.test.ts packages/daemon/test/app-channel.test.ts packages/daemon/test/app-channel-fd.test.ts packages/daemon/test/windows-app-channel-addon.test.ts
+
diff --git a/.gitignore b/.gitignore
index d1d6c6c..5b46aa4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,3 +16,10 @@ apps/desktop/src-tauri/gen/
# Declarations emitted next to sources by accident
packages/*/src/**/*.d.ts
+
+# Explicit Windows addon build outputs
+/packages/daemon/native/*.node
+/packages/daemon/native/*.obj
+/packages/daemon/native/*.lib
+/packages/daemon/native/*.exp
+/packages/daemon/native/*.pdb
diff --git a/packages/daemon/README.md b/packages/daemon/README.md
new file mode 100644
index 0000000..04123a9
--- /dev/null
+++ b/packages/daemon/README.md
@@ -0,0 +1,21 @@
+# Gentle Dot daemon
+
+## Explicit Windows addon build
+
+On Windows, use an **existing** MSVC/Windows SDK developer environment with
+`INCLUDE` and `LIB` configured for the same architecture as Node. Supply matching
+Node headers, architecture/version-compatible `node.lib`, and the compiler path.
+The build script does not install or download inputs, use node-gyp, or add dependencies.
+
+```powershell
+# From packages/daemon; substitute your existing absolute input paths.
+node scripts/build-windows-stop.mjs --help
+node scripts/build-windows-stop.mjs --compiler "C:\existing\cl.exe" --headers "C:\existing\node\include\node" --node-lib "C:\existing\node.lib"
+```
+
+The package command is `pnpm run build:windows-stop -- <same arguments>`.
+The compiler emits `native/windows-stop.node` and local compiler/linker artifacts.
+It must not be cross-built with mismatched Node/import-library architecture.
+Source execution loads `packages/daemon/native/windows-stop.node`.
+This slice exports only the app channel; the stop listener and runtime staging
+are not included yet. Windows CI provisions matching build inputs explicitly.
diff --git a/packages/daemon/native/windows-stop.cc b/packages/daemon/native/windows-stop.cc
new file mode 100644
index 0000000..3eea758
--- /dev/null
+++ b/packages/daemon/native/windows-stop.cc
@@ -0,0 +1,11 @@
+// App-channel-only entry point; the stop listener (createStopListener) joins
+// this module in a later PR.
+#include "windows-app-channel-napi.h"
+
+namespace {
+napi_value Init(napi_env env, napi_value exports) {
+ if (gentle_dot::app_channel::RegisterAppChannel(env, exports) != napi_ok) return nullptr;
+ return exports;
+}
+} // namespace
+NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)
diff --git a/packages/daemon/package.json b/packages/daemon/package.json
index 38fa40d..06f20db 100644
--- a/packages/daemon/package.json
+++ b/packages/daemon/package.json
@@ -7,7 +7,8 @@
"gentle-dot": "./src/cli.ts"
},
"scripts": {
- "build:runtime": "node scripts/build-runtime.ts"
+ "build:runtime": "node scripts/build-runtime.ts",
+ "build:windows-stop": "node scripts/build-windows-stop.mjs"
},
"dependencies": {
"@earendil-works/pi-ai": "1.4.0",
diff --git a/packages/daemon/scripts/build-windows-stop.mjs b/packages/daemon/scripts/build-windows-stop.mjs
new file mode 100644
index 0000000..0b9b021
--- /dev/null
+++ b/packages/daemon/scripts/build-windows-stop.mjs
@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+// Explicit production addon build. Uses existing inputs only; never installs or downloads.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const usage =
+ "usage: build-windows-stop --compiler <absolute cl.exe> --headers <Node include/node> --node-lib <node.lib>\nRun in an existing MSVC/Windows SDK developer environment (INCLUDE and LIB). No inputs are downloaded.\n";
+const args = process.argv.slice(2).filter((arg) => arg !== "--");
+if (args.includes("--help")) {
+ process.stdout.write(usage);
+} else {
+ if (process.platform !== "win32") throw new Error("Windows stop addon must be built on Windows");
+ const values = new Map();
+ for (let index = 0; index < args.length; index += 2) {
+ const flag = args[index];
+ const value = args[index + 1];
+ if (!["--compiler", "--headers", "--node-lib"].includes(flag) || !value || values.has(flag)) {
+ throw new Error(usage);
+ }
+ values.set(flag, value);
+ }
+ const compiler = values.get("--compiler");
+ const headers = values.get("--headers");
+ const nodeLib = values.get("--node-lib");
+ if (
+ ![compiler, headers, nodeLib].every(
+ (path) => typeof path === "string" && isAbsolute(path) && existsSync(path),
+ ) ||
+ !existsSync(join(headers, "node_api.h")) ||
+ !process.env.INCLUDE ||
+ !process.env.LIB
+ ) {
+ throw new Error(usage);
+ }
+ const native = fileURLToPath(new URL("../native/", import.meta.url));
+ const source = join(native, "windows-stop.cc");
+ const channelSource = join(native, "windows-app-channel.cc");
+ const channelObject = join(native, "windows-app-channel.obj");
+ const streamSource = join(native, "windows-app-channel-stream.cc");
+ const streamObject = join(native, "windows-app-channel-stream.obj");
+ const napiSource = join(native, "windows-app-channel-napi.cc");
+ const napiObject = join(native, "windows-app-channel-napi.obj");
+ if (
+ ![
+ source,
+ channelSource,
+ streamSource,
+ napiSource,
+ join(native, "windows-app-channel.h"),
+ join(native, "windows-app-channel-stream.h"),
+ join(native, "windows-app-channel-napi.h"),
+ ].every(existsSync)
+ ) {
+ throw new Error("Production Windows native source is missing");
+ }
+ mkdirSync(dirname(source), { recursive: true });
+ // Separate translation-unit invocation: /Fo must not name one file for two sources.
+ // Host libuv imports resolve through node.lib below; never link a separate libuv.
+ const channelResult = spawnSync(
+ compiler,
+ [
+ "/nologo",
+ "/c",
+ "/EHsc",
+ "/std:c++17",
+ "/O2",
+ "/MD",
+ `/I${headers}`,
+ channelSource,
+ `/Fo${channelObject}`,
+ ],
+ { cwd: native, stdio: "inherit", shell: false },
+ );
+ if (channelResult.error) throw new Error("Windows channel compiler could not be started");
+ if (channelResult.status !== 0) {
+ process.exit(channelResult.status ?? 1);
+ }
+ const streamResult = spawnSync(
+ compiler,
+ [
+ "/nologo",
+ "/c",
+ "/EHsc",
+ "/std:c++17",
+ "/O2",
+ "/MD",
+ `/I${headers}`,
+ streamSource,
+ `/Fo${streamObject}`,
+ ],
+ { cwd: native, stdio: "inherit", shell: false },
+ );
+ if (streamResult.error) throw new Error("Windows channel stream compiler could not be started");
+ if (streamResult.status !== 0) {
+ process.exit(streamResult.status ?? 1);
+ }
+ const napiResult = spawnSync(
+ compiler,
+ [
+ "/nologo",
+ "/c",
+ "/EHsc",
+ "/std:c++17",
+ "/O2",
+ "/MD",
+ "/DNAPI_VERSION=8",
+ `/I${headers}`,
+ napiSource,
+ `/Fo${napiObject}`,
+ ],
+ { cwd: native, stdio: "inherit", shell: false },
+ );
+ if (napiResult.error) throw new Error("Windows channel Node-API compiler could not be started");
+ if (napiResult.status !== 0) {
+ process.exit(napiResult.status ?? 1);
+ }
+ const result = spawnSync(
+ compiler,
+ [
+ "/nologo",
+ "/LD",
+ "/EHsc",
+ "/std:c++17",
+ "/O2",
+ "/MD",
+ "/DNAPI_VERSION=8",
+ "/DNODE_GYP_MODULE_NAME=windows_stop",
+ `/I${headers}`,
+ source,
+ channelObject,
+ streamObject,
+ napiObject,
+ `/Fo${join(native, "windows-stop.obj")}`,
+ "/link",
+ "/INCREMENTAL:NO",
+ `/OUT:${join(native, "windows-stop.node")}`,
+ `/IMPLIB:${join(native, "windows-stop.lib")}`,
+ `/PDB:${join(native, "windows-stop.pdb")}`,
+ nodeLib,
+ "kernel32.lib",
+ ],
+ { cwd: native, stdio: "inherit", shell: false },
+ );
+ if (result.error) throw new Error("Windows stop compiler could not be started");
+ process.exitCode = result.status ?? 1;
+}
diff --git a/packages/daemon/src/windows-app-channel.ts b/packages/daemon/src/windows-app-channel.ts
index 89a699c..54a1e5c 100644
--- a/packages/daemon/src/windows-app-channel.ts
+++ b/packages/daemon/src/windows-app-channel.ts
@@ -108,7 +108,13 @@ class WindowsAppChannelDuplex extends Duplex {
#mode: "drain" | "abort" = "abort";
constructor(options: WindowsAppChannelOptions, facts: StartupFacts, loadNative: () => NativeAppChannelAPI) {
- super({ readableHighWaterMark: 65536, writableHighWaterMark: 65536, autoDestroy: true });
+ super({
+ readableHighWaterMark: 65536,
+ writableHighWaterMark: 65536,
+ autoDestroy: true,
+ // _write relies on Buffer chunks: byte length matches the native 2 MiB limit.
+ decodeStrings: true,
+ });
if (options.exclusiveFd3Startup !== true || !facts.mainThread)
throw new Error("Exclusive main-thread fd3 startup required");
if (facts.ipcChannel || facts.ipcConnected || facts.channelFdPresent)
diff --git a/packages/daemon/test/fixtures/windows-app-channel-refuse.mjs b/packages/daemon/test/fixtures/windows-app-channel-refuse.mjs
new file mode 100644
index 0000000..732c23e
--- /dev/null
+++ b/packages/daemon/test/fixtures/windows-app-channel-refuse.mjs
@@ -0,0 +1,16 @@
+import { createRequire } from "node:module";
+
+// Set after bootstrap: Node may consume/delete NODE_CHANNEL_FD during startup.
+if (process.argv[3] === "ipc") process.env.NODE_CHANNEL_FD = "3";
+else delete process.env.NODE_CHANNEL_FD;
+const addon = createRequire(import.meta.url)(process.argv[2]);
+const failures = [];
+for (let attempt = 0; attempt < (process.argv[3] === "twice" ? 2 : 1); attempt++) {
+ try {
+ addon.adoptAppChannelFd3(true);
+ throw new Error("Unexpected adoption success");
+ } catch (error) {
+ failures.push({ message: error.message, code: error.code, evidence: error.evidence });
+ }
+}
+process.stdout.write(JSON.stringify(failures));
diff --git a/packages/daemon/test/windows-app-channel-addon.test.ts b/packages/daemon/test/windows-app-channel-addon.test.ts
new file mode 100644
index 0000000..41099d2
--- /dev/null
+++ b/packages/daemon/test/windows-app-channel-addon.test.ts
@@ -0,0 +1,74 @@
+import { spawnSync } from "node:child_process";
+import { closeSync, existsSync, openSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { windowsStopArtifact } from "../src/windows-stop.ts";
+
+const artifact = windowsStopArtifact();
+const fixture = new URL("./fixtures/windows-app-channel-refuse.mjs", import.meta.url);
+// Windows CI must fail, not skip, if its preceding addon build did not produce the artifact.
+const skipReason =
+ process.platform !== "win32"
+ ? "real addon requires Windows"
+ : !existsSync(artifact) && !process.env.CI
+ ? "build native/windows-stop.node to run locally"
+ : undefined;
+// Failure enum in native/windows-app-channel.h (zero-based).
+const NODE_IPC_COLLISION = 1;
+const NOT_PIPE = 4;
+
+function refuse(mode: "ipc" | "file" | "twice") {
+ expect(existsSync(artifact), "Windows CI requires the built windows-stop.node artifact").toBe(true);
+ // Inherit a regular file as fd3, never a pipe. No temporary file or cleanup race.
+ const fd = openSync(fixture, "r");
+ try {
+ const env = { ...process.env };
+ delete env.NODE_CHANNEL_FD;
+ const child = spawnSync(process.execPath, [fileURLToPath(fixture), fileURLToPath(artifact), mode], {
+ env,
+ stdio: ["ignore", "pipe", "pipe", fd],
+ encoding: "utf8",
+ timeout: 10_000,
+ });
+ expect(child.error).toBeUndefined();
+ expect(child.signal).toBeNull();
+ expect(child.status).toBe(0);
+ expect(child.stderr).toBe("");
+ return JSON.parse(child.stdout);
+ } finally {
+ closeSync(fd);
+ }
+}
+function expectRefusal(result: unknown, failure: number) {
+ expect(result).toEqual({
+ message: "App channel adoption failed; refuse startup",
+ evidence: {
+ failure,
+ win32Error: expect.any(Number),
+ ntStatus: 0,
+ uvError: 0,
+ streamError: 0,
+ originalRemoved: false,
+ },
+ });
+}
+
+describe.skipIf(Boolean(skipReason))(`real Windows app-channel addon (${skipReason ?? "built"})`, () => {
+ it("refuses visible NODE_CHANNEL_FD=3 with collision evidence", () => {
+ const [result] = refuse("ipc");
+ expectRefusal(result, NODE_IPC_COLLISION);
+ expect(result.evidence.win32Error).toBe(0);
+ });
+ it("refuses a regular file at fd3 with not_pipe evidence", () => {
+ const [result] = refuse("file");
+ expectRefusal(result, NOT_PIPE);
+ });
+ it("refuses a second adoption attempt even after the first failed", () => {
+ const [first, second] = refuse("twice");
+ expectRefusal(first, NOT_PIPE);
+ expect(second).toEqual({
+ message: "Process app channel adoption already attempted",
+ code: "ERR_APP_CHANNEL_ADOPTION",
+ });
+ });
+});
diff --git a/packages/daemon/test/windows-app-channel.test.ts b/packages/daemon/test/windows-app-channel.test.ts
index 4707132..f9cfec8 100644
--- a/packages/daemon/test/windows-app-channel.test.ts
+++ b/packages/daemon/test/windows-app-channel.test.ts
@@ -33,6 +33,7 @@ function fixture() {
let uncertain = false;
let released: NativeAppChannelSnapshot | undefined;
const calls: string[] = [];
+ const writes: Buffer[] = [];
const owner: NativeAppChannelOwner = {
status() {
expect(this).toBe(owner);
@@ -52,6 +53,7 @@ function fixture() {
return result;
},
write(chunk) {
+ writes.push(chunk);
expect(this).toBe(owner);
calls.push(`write:${chunk.toString()}`);
if (pressure) return { admission: "backpressure", ticket: 0n };
@@ -90,6 +92,7 @@ function fixture() {
return {
status,
calls,
+ writes,
factory,
stream,
data(value: Buffer) {
@@ -121,6 +124,17 @@ beforeEach(() => vi.useFakeTimers());
afterEach(() => vi.useRealTimers());
describe("Windows app channel lifecycle integration", () => {
+ it("decodes string writes into Buffer bytes before native admission", async () => {
+ const f = fixture();
+ const s = f.stream();
+ s.write("é");
+ expect(f.writes).toHaveLength(1);
+ expect(Buffer.isBuffer(f.writes[0])).toBe(true);
+ expect(f.writes[0]).toEqual(Buffer.from("é"));
+ f.status.completedWrite = f.status.acceptedWrite;
+ await tick();
+ await terminate(f, s);
+ });
it("a first abort makes later AppChannel drain reject instead of certifying closure", async () => {
const f = fixture();
const s = f.stream();