@devries-cameron20 / t3code Mirror · read-only / commits / 58a407c093
Fork 0

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 +};