The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 22, 08:15 UTC
feat(desktop): prepare server bytecode cache in native builds (#28572)
Yash Singh committed
Nov 1, 2026 at 04:42 UTC
58a407c0932b8ffaea8def12b32abca8d9f6cb7c
11 files changed
+345
-12
apps/desktop/scripts/main-process-bundle.test.mjs
+5
-6
@@ -3,6 +3,7 @@ import * as NodeFSP from "node:fs/promises";
3
import * as NodeOS from "node:os";
4
import * as NodePath from "node:path";
5
import * as NodeVM from "node:vm";
6
+import * as NodeURL from "node:url";
7
import { build } from "vite-plus/pack";
8
import { assert, it } from "vite-plus/test";
9
@@ -114,18 +115,16 @@ it("loads the emitted packaged boot entry and backend cache preload", async () =
115
const directory = await NodeFSP.mkdtemp(NodePath.join(NodeOS.tmpdir(), "t3-desktop-boot-"));
116
try {
117
const entries = ["src/boot.ts", "src/compileCache.ts"];
117
- await NodeFSP.mkdir(NodePath.join(directory, "src"));
118
- await Promise.all(
119
- entries.map((entry) =>
120
- NodeFSP.copyFile(new URL(`../${entry}`, import.meta.url), NodePath.join(directory, entry)),
121
- ),
122
- );
118
assert.ok(Array.isArray(desktopConfig.pack));
119
for (const packConfig of desktopConfig.pack) {
120
if (!Array.isArray(packConfig.entry)) continue;
121
if (!packConfig.entry.some((entry) => entries.includes(entry))) continue;
122
await build({
123
...packConfig,
124
+ entry: packConfig.entry.map((entry) =>
125
+ NodeURL.fileURLToPath(new URL(`../${entry}`, import.meta.url)),
126
+ ),
127
+ outDir: NodePath.join(directory, "dist-electron"),
128
config: false,
129
cwd: directory,
130
tsconfig: false,
apps/desktop/src/compileCache.ts
+9
-2
@@ -2,16 +2,23 @@
2
import * as NodeModule from "node:module";
3
import * as NodeOS from "node:os";
4
import * as NodePath from "node:path";
5
+import { enablePreparedServerCache } from "../../../scripts/lib/server-compile-cache.ts";
6
7
// Linux /tmp is shared; macOS and Windows temp dirs are per user.
8
// AppImage mounts change paths each launch, so Node's path-keyed cache would miss and accumulate copies.
9
try {
9
- if (!process.env.APPIMAGE) {
10
+ if (!process.env.APPIMAGE || process.env.ELECTRON_RUN_AS_NODE === "1") {
11
const cacheRoot =
12
// oxlint-disable-next-line t3code/no-global-process-runtime -- Loads before any Effect runtime.
13
process.platform === "linux"
14
? process.env.XDG_CACHE_HOME || NodePath.join(NodeOS.homedir(), ".cache")
15
: NodeOS.tmpdir();
15
- NodeModule.enableCompileCache(NodePath.join(cacheRoot, "t3code", "compile-cache"));
16
+ const directory = NodePath.join(cacheRoot, "t3code", "compile-cache");
17
+ const prepared =
18
+ process.env.ELECTRON_RUN_AS_NODE === "1" &&
19
+ enablePreparedServerCache(process.argv[1] ?? "", directory);
20
+ if (!prepared && !process.env.APPIMAGE) {
21
+ NodeModule.enableCompileCache(directory);
22
+ }
23
}
24
} catch {}
apps/desktop/src/serverCompileCache.ts
new
+1
@@ -0,0 +1 @@
1
+export { generatePreparedServerCache } from "../../../scripts/lib/server-compile-cache.ts";
apps/desktop/vite.config.ts
+1
-1
@@ -93,7 +93,7 @@ export default defineConfig({
93
dts: false,
94
sourcemap: true,
95
outExtensions: () => ({ js: ".cjs" }),
96
- entry: ["src/boot.ts", "src/compileCache.ts"],
96
+ entry: ["src/boot.ts", "src/compileCache.ts", "src/serverCompileCache.ts"],
97
clean: false,
98
deps: {
99
neverBundle: (id) => id === "./main.cjs" || id === "./compileCache.cjs",
apps/server/src/compileCache.ts
+5
-3
@@ -2,6 +2,8 @@ import * as NodeModule from "node:module";
2
import * as Effect from "effect/Effect";
3
4
// Windows force-kills on quit; persist the cache after startup.
5
-export const flushCompileCache = Effect.try(() => NodeModule.flushCompileCache()).pipe(
6
- Effect.ignore,
7
-);
5
+export const flushCompileCache = Effect.try(() => {
6
+ if (!Reflect.get(globalThis, Symbol.for("t3code.preparedServerCache"))) {
7
+ NodeModule.flushCompileCache();
8
+ }
9
+}).pipe(Effect.ignore);
docs/operations/development.md
+22
@@ -261,6 +261,28 @@ DMGs default to the host architecture. Use `--arch` to choose another target and
261
to retain packaging files for inspection. Run `vp run dist:desktop:artifact --help` for other
262
options.
263
264
+### Prepared server bytecode
265
+
266
+Native desktop artifact builds generate server bytecode with the packaged Electron executable,
267
+after ASAR creation and before signing. Cross-platform and cross-architecture builds skip this
268
+step explicitly. CLI, SEA and WSL runtimes keep their existing behavior; only desktop backend
269
+imports covered by generation receive prepared bytecode. Worker-only modules compile normally.
270
+
271
+Electron's Node 24 cache has no read-only option and includes the producer UID in its directory
272
+name. The backend links individual prepared files into its writable cache with keys for the
273
+installed module paths. Node replaces files atomically, so regeneration cannot write through those
274
+links into signed resources. Windows uses hard links and falls back to normal caching when volumes
275
+differ or resource permissions prevent linking. Protected installations therefore may not reuse
276
+prepared bytecode. No cache bytes are copied during startup. AppImage backends discard their links
277
+on normal exit because each mount changes module paths.
278
+
279
+The key calculation follows Node's internal portable ESM format. Generation checks that the
280
+packaged engine produced the expected CLI entry and fails the build if that format changes.
281
+The manifest also checks Electron, Node, OS, architecture and V8's flags-sensitive version tag.
282
+Missing or rejected entries compile from the shipped JavaScript. Prepared backends skip the
283
+explicit startup flush; Node can persist missing entries on normal exit. The writable fallback
284
+keeps the explicit flush needed when Windows force-kills the backend.
285
+
286
### Linux AppImage prerequisites
287
288
Build on Linux because the browser-secret helper links against the host's libsecret. Install
knip.jsonc
+2
@@ -32,6 +32,7 @@
32
"mobile-native-client.ts",
33
"setup-worktree.ts",
34
"sign-macos.ts",
35
+ "prepare-server-compile-cache.cjs",
36
"smoke-desktop-app.ts",
37
"verify-windows-desktop-artifact.ts",
38
],
@@ -73,6 +74,7 @@
74
"src/snapShot/SnapShotAccessibilityWorker.ts!",
75
"src/boot.ts!",
76
"src/compileCache.ts!",
77
+ "src/serverCompileCache.ts!",
78
"src/main.ts!",
79
"src/preload.ts!",
80
"src/preview-pick-preload.ts!",
scripts/build-desktop-artifact.ts
+1
@@ -2771,6 +2771,7 @@ export const createBuildConfig = Effect.fn("createBuildConfig")(function* (
2771
arch?: typeof BuildArch.Type,
2772
) {
2773
const buildConfig: Record<string, unknown> = {
2774
+ afterPack: (yield* Path.Path).join(yield* RepoRoot, "scripts/prepare-server-compile-cache.cjs"),
2775
appId: DESKTOP_APP_ID,
2776
productName: resolveDesktopProductName(version),
2777
artifactName: "T3-Code-${version}-${arch}.${ext}",
scripts/lib/server-compile-cache.test.ts
new
+108
@@ -0,0 +1,108 @@
1
+// @effect-diagnostics nodeBuiltinImport:off
2
+import * as NodeFS from "node:fs";
3
+import * as NodeOS from "node:os";
4
+import * as NodePath from "node:path";
5
+import { expect, it } from "vite-plus/test";
6
+import { cacheKey, seedPreparedCache } from "./server-compile-cache.ts";
7
+
8
+it("seeds relocated cache entries without allowing writes into shipped resources", () => {
9
+ const root = NodeFS.realpathSync(
10
+ NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-prepared-test-")),
11
+ );
12
+ try {
13
+ const prepared = NodePath.join(root, "resources", "server-compile-cache");
14
+ const active = NodePath.join(root, "user", "different-uid-tag");
15
+ NodeFS.mkdirSync(prepared, { recursive: true });
16
+ NodeFS.mkdirSync(active, { recursive: true });
17
+ NodeFS.writeFileSync(NodePath.join(prepared, "12345678"), "prepared bytes");
18
+ const manifest = {
19
+ format: 1,
20
+ runtime: "matching",
21
+ entries: [{ module: "app.asar/apps/server/dist/chunk.mjs", file: "12345678" }],
22
+ };
23
+ NodeFS.writeFileSync(NodePath.join(prepared, "manifest.json"), JSON.stringify(manifest));
24
+ expect(seedPreparedCache(prepared, active, "wrong-engine")).toBe(false);
25
+ expect(seedPreparedCache(prepared, active, "matching")).toBe(true);
26
+ const key = cacheKey(active, NodePath.join(root, "resources", manifest.entries[0]!.module));
27
+ expect(NodeFS.readFileSync(NodePath.join(active, key), "utf8")).toBe("prepared bytes");
28
+ // Node persists by replacing the directory entry, never by overwriting the linked inode.
29
+ NodeFS.rmSync(NodePath.join(active, key));
30
+ NodeFS.writeFileSync(NodePath.join(active, key), "runtime replacement");
31
+ expect(NodeFS.readFileSync(NodePath.join(prepared, "12345678"), "utf8")).toBe("prepared bytes");
32
+ expect(seedPreparedCache(prepared, active, "matching")).toBe(true);
33
+ expect(NodeFS.readFileSync(NodePath.join(active, key), "utf8")).toBe("runtime replacement");
34
+ const missing = { module: "app.asar/apps/server/dist/missing.mjs", file: "87654321" };
35
+ for (const entries of [
36
+ [...manifest.entries, missing],
37
+ [missing, ...manifest.entries],
38
+ ]) {
39
+ NodeFS.writeFileSync(
40
+ NodePath.join(prepared, "manifest.json"),
41
+ JSON.stringify({ ...manifest, entries }),
42
+ );
43
+ expect(seedPreparedCache(prepared, active, "matching")).toBe(false);
44
+ }
45
+ NodeFS.writeFileSync(NodePath.join(prepared, "manifest.json"), "corrupt");
46
+ expect(seedPreparedCache(prepared, active, "matching")).toBe(false);
47
+ expect(seedPreparedCache(NodePath.join(root, "missing"), active, "matching")).toBe(false);
48
+ } finally {
49
+ NodeFS.rmSync(root, { recursive: true, force: true });
50
+ }
51
+});
52
+
53
+it.each(["app", "server"])(
54
+ "generates %s.asar cache with the consumer engine and falls back after damage",
55
+ async (archive) => {
56
+ const { spawnSync } = await import("node:child_process");
57
+ const helper = new URL("./server-compile-cache.ts", import.meta.url).href;
58
+ const root = NodeFS.realpathSync(
59
+ NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-cache-engine-")),
60
+ );
61
+ const run = (code: string) => {
62
+ const env = {
63
+ ...process.env,
64
+ NODE_DEBUG_NATIVE: "COMPILE_CACHE",
65
+ NODE_COMPILE_CACHE: undefined,
66
+ NODE_DISABLE_COMPILE_CACHE: undefined,
67
+ };
68
+ const result = spawnSync(process.execPath, ["--input-type=module", "-e", code], {
69
+ env,
70
+ encoding: "utf8",
71
+ });
72
+ expect(result.status, result.stderr).toBe(0);
73
+ return result.stderr;
74
+ };
75
+ try {
76
+ const producer = NodePath.join(root, "producer", "resources");
77
+ const consumer = NodePath.join(root, "relocated", "resources");
78
+ const relative = `${archive}.asar/apps/server/dist/binCli-fixture.mjs`;
79
+ NodeFS.mkdirSync(NodePath.dirname(NodePath.join(producer, relative)), { recursive: true });
80
+ NodeFS.writeFileSync(NodePath.join(producer, relative), "export const answer = 42;");
81
+ run(
82
+ `import {generatePreparedServerCache} from ${JSON.stringify(helper)}; await generatePreparedServerCache(${JSON.stringify(producer)});`,
83
+ );
84
+ NodeFS.cpSync(producer, consumer, { recursive: true });
85
+ const consume = (home: string, appImage = false) =>
86
+ run(
87
+ `if (${appImage}) process.env.APPIMAGE = "fixture"; import {enablePreparedServerCache} from ${JSON.stringify(helper)}; import {pathToFileURL} from 'node:url'; if(!enablePreparedServerCache(${JSON.stringify(NodePath.join(consumer, relative))},${JSON.stringify(NodePath.join(root, home))})) throw Error('cache disabled'); const m = await import(pathToFileURL(${JSON.stringify(NodePath.join(consumer, relative))}).href); if(m.answer!==42) throw Error('source fallback failed');`,
88
+ );
89
+ const prepared = NodePath.join(consumer, "server-compile-cache");
90
+ NodeFS.chmodSync(prepared, 0o555);
91
+ expect(consume("first-user")).toContain("was accepted");
92
+ expect(consume("appimage-user", true)).toContain("was accepted");
93
+ expect(NodeFS.readdirSync(NodePath.join(root, "appimage-user", "server"))).toEqual([]);
94
+ NodeFS.chmodSync(prepared, 0o755);
95
+ for (const file of NodeFS.readdirSync(prepared).filter((file) => file !== "manifest.json")) {
96
+ NodeFS.writeFileSync(NodePath.join(prepared, file), "broken");
97
+ }
98
+ expect(consume("second-user")).toContain("was not initialized");
99
+ for (const file of NodeFS.readdirSync(prepared).filter((file) => file !== "manifest.json")) {
100
+ expect(NodeFS.readFileSync(NodePath.join(prepared, file), "utf8")).toBe("broken");
101
+ }
102
+ NodeFS.rmSync(prepared, { recursive: true });
103
+ expect(consume("third-user")).toContain("was not initialized");
104
+ } finally {
105
+ NodeFS.rmSync(root, { recursive: true, force: true });
106
+ }
107
+ },
108
+);
scripts/lib/server-compile-cache.ts
new
+136
@@ -0,0 +1,136 @@
1
+/* oxlint-disable t3code/no-global-process-runtime -- Runs in the packaged engine before an Effect runtime exists. */
2
+// @effect-diagnostics nodeBuiltinImport:off
3
+import * as NodeFS from "node:fs";
4
+import * as NodePath from "node:path";
5
+import * as NodeModule from "node:module";
6
+import * as NodeV8 from "node:v8";
7
+import * as NodeZlib from "node:zlib";
8
+import * as NodeURL from "node:url";
9
+
10
+export const runtimeIdentity = () =>
11
+ [
12
+ process.versions.electron,
13
+ process.version,
14
+ process.platform,
15
+ process.arch,
16
+ NodeV8.cachedDataVersionTag(),
17
+ ].join("-");
18
+
19
+// Node 24's portable key is CRC32 of the one-byte ESM type followed by the relative filename.
20
+// Generation verifies this against files produced by the packaged engine before shipping them.
21
+export const cacheKey = (active: string, filename: string) =>
22
+ NodeZlib.crc32(NodePath.relative(active, filename), NodeZlib.crc32(Buffer.from([1])))
23
+ .toString(16)
24
+ .padStart(8, "0");
25
+
26
+export function seedPreparedCache(prepared: string, active: string, runtime: string): boolean {
27
+ try {
28
+ const manifest: unknown = JSON.parse(
29
+ NodeFS.readFileSync(NodePath.join(prepared, "manifest.json"), "utf8"),
30
+ );
31
+ if (
32
+ typeof manifest !== "object" ||
33
+ manifest === null ||
34
+ !("format" in manifest) ||
35
+ manifest.format !== 1 ||
36
+ !("runtime" in manifest) ||
37
+ manifest.runtime !== runtime ||
38
+ !("entries" in manifest) ||
39
+ !Array.isArray(manifest.entries) ||
40
+ manifest.entries.length === 0
41
+ )
42
+ return false;
43
+ for (const entry of manifest.entries) {
44
+ if (
45
+ typeof entry?.module !== "string" ||
46
+ typeof entry?.file !== "string" ||
47
+ !/^[a-f0-9]{8}$/.test(entry.file) ||
48
+ !/^(app|server)\.asar\/apps\/server\/dist\/[^/\\]+\.mjs$/.test(entry.module)
49
+ )
50
+ return false;
51
+ const source = NodePath.join(prepared, entry.file);
52
+ const destination = NodePath.join(
53
+ active,
54
+ cacheKey(active, NodePath.join(NodePath.dirname(prepared), entry.module)),
55
+ );
56
+ try {
57
+ // Node replaces cache files atomically. A directory link would instead allow writes into signed resources.
58
+ if (process.platform === "win32") NodeFS.linkSync(source, destination);
59
+ else NodeFS.symlinkSync(source, destination);
60
+ } catch {}
61
+ if (!NodeFS.existsSync(destination)) return false;
62
+ }
63
+ return true;
64
+ } catch {
65
+ return false;
66
+ }
67
+}
68
+
69
+export function enablePreparedServerCache(entry: string, cacheRoot: string): boolean {
70
+ try {
71
+ const archive = entry.match(/^(.*[\\/](?:app|server)\.asar)[\\/]/)?.[1];
72
+ if (!archive) return false;
73
+ const resources = NodeFS.realpathSync(NodePath.dirname(archive));
74
+ // Keep different installations and builds separate without reading or copying their source files.
75
+ const prepared = NodePath.join(resources, "server-compile-cache");
76
+ if (process.env.APPIMAGE && !NodeFS.existsSync(NodePath.join(prepared, "manifest.json")))
77
+ return false;
78
+ const identity = NodeZlib.crc32(resources).toString(16);
79
+ NodeFS.mkdirSync(NodePath.join(cacheRoot, "server"), { recursive: true });
80
+ const directory = process.env.APPIMAGE
81
+ ? NodeFS.mkdtempSync(NodePath.join(cacheRoot, "server", "appimage-"))
82
+ : NodePath.join(cacheRoot, "server", identity);
83
+ if (process.env.APPIMAGE) {
84
+ // Each mount has different module paths; discard its links rather than accumulating caches.
85
+ process.once("exit", () => {
86
+ try {
87
+ NodeFS.rmSync(directory, { recursive: true, force: true });
88
+ } catch {}
89
+ });
90
+ }
91
+ const result = NodeModule.enableCompileCache({
92
+ directory,
93
+ portable: true,
94
+ });
95
+ const active = NodeModule.getCompileCacheDir();
96
+ if (result.status !== NodeModule.constants.compileCacheStatus.ENABLED || !active) return false;
97
+ const seeded = seedPreparedCache(prepared, active, runtimeIdentity());
98
+ if (seeded) Reflect.set(globalThis, Symbol.for("t3code.preparedServerCache"), true);
99
+ return true;
100
+ } catch {
101
+ return false;
102
+ }
103
+}
104
+
105
+export async function generatePreparedServerCache(resourcesInput: string): Promise<void> {
106
+ const resources = NodeFS.realpathSync(resourcesInput);
107
+ const prepared = NodePath.join(resources, "server-compile-cache");
108
+ const archive = NodeFS.existsSync(NodePath.join(resources, "server.asar"))
109
+ ? "server.asar"
110
+ : "app.asar";
111
+ const dist = NodePath.join(resources, archive, "apps/server/dist");
112
+ NodeFS.mkdirSync(prepared, { recursive: true });
113
+ const result = NodeModule.enableCompileCache({ directory: prepared, portable: true });
114
+ if (result.status !== NodeModule.constants.compileCacheStatus.ENABLED)
115
+ throw new Error("Cannot enable release compile cache");
116
+ const cli = NodeFS.readdirSync(dist).find((file) => /^binCli-.*\.mjs$/.test(file));
117
+ if (!cli) throw new Error("Missing bundled server CLI");
118
+ await import(NodeURL.pathToFileURL(NodePath.join(dist, cli)).href);
119
+ NodeModule.flushCompileCache();
120
+ const active = NodeModule.getCompileCacheDir()!;
121
+ const entries = NodeFS.readdirSync(dist)
122
+ .filter((file) => file.endsWith(".mjs"))
123
+ .flatMap((file) => {
124
+ const key = cacheKey(active, NodePath.join(dist, file));
125
+ if (!NodeFS.existsSync(NodePath.join(active, key))) return [];
126
+ NodeFS.copyFileSync(NodePath.join(active, key), NodePath.join(prepared, key));
127
+ return [{ module: `${archive}/apps/server/dist/${file}`, file: key }];
128
+ });
129
+ if (!entries.some((entry) => entry.module.endsWith(`/${cli}`)))
130
+ throw new Error("Packaged engine cache key format is unsupported");
131
+ NodeFS.writeFileSync(
132
+ NodePath.join(prepared, "manifest.json"),
133
+ JSON.stringify({ format: 1, runtime: runtimeIdentity(), entries }),
134
+ );
135
+ NodeFS.rmSync(active, { recursive: true });
136
+}
scripts/prepare-server-compile-cache.cjs
new
+55
@@ -0,0 +1,55 @@
1
+/* oxlint-disable t3code/no-global-process-runtime -- Packaging must compare the build host with the executable target. */
2
+const { spawnSync } = require("node:child_process");
3
+const path = require("node:path");
4
+const fs = require("node:fs");
5
+const os = require("node:os");
6
+
7
+// afterPack runs before signing and installer creation, against the final ASAR layout.
8
+module.exports = async ({ appOutDir, electronPlatformName, arch, packager }) => {
9
+ const targetArch = ["ia32", "x64", "armv7l", "arm64", "universal"][arch];
10
+ if (electronPlatformName !== process.platform || targetArch !== process.arch) {
11
+ console.log(
12
+ `[server-compile-cache] Skipping unexecutable target ${electronPlatformName}/${targetArch}`,
13
+ );
14
+ return;
15
+ }
16
+ const product = packager.appInfo.productFilename;
17
+ const resources =
18
+ electronPlatformName === "darwin"
19
+ ? path.join(appOutDir, `${product}.app`, "Contents", "Resources")
20
+ : path.join(appOutDir, "resources");
21
+ const executable =
22
+ electronPlatformName === "darwin"
23
+ ? path.join(appOutDir, `${product}.app`, "Contents", "MacOS", product)
24
+ : path.join(
25
+ appOutDir,
26
+ electronPlatformName === "win32" ? `${product}.exe` : packager.executableName,
27
+ );
28
+ const helper = path.join(
29
+ resources,
30
+ "app.asar",
31
+ "apps/desktop/dist-electron/serverCompileCache.cjs",
32
+ );
33
+ const env = { ...process.env, ELECTRON_RUN_AS_NODE: "1" };
34
+ for (const name of Object.keys(env)) {
35
+ if (name.startsWith("NODE_") || name.startsWith("T3CODE_")) delete env[name];
36
+ }
37
+ const state = fs.mkdtempSync(path.join(os.tmpdir(), "t3-release-cache-"));
38
+ env.T3CODE_HOME = state;
39
+ let result;
40
+ try {
41
+ result = spawnSync(
42
+ executable,
43
+ [
44
+ "-e",
45
+ `require(${JSON.stringify(helper)}).generatePreparedServerCache(${JSON.stringify(resources)}).then(()=>process.exit(0),e=>{console.error(e);process.exit(1)})`,
46
+ ],
47
+ { env, encoding: "utf8", timeout: 120000 },
48
+ );
49
+ } finally {
50
+ fs.rmSync(state, { recursive: true, force: true });
51
+ }
52
+ if (result.status !== 0)
53
+ throw new Error(`Server compile cache generation failed: ${result.error || result.stderr}`);
54
+ console.log("[server-compile-cache] Prepared server bytecode with packaged Electron");
55
+};