The best way to control Claude Code, Codex and more from any computer or phone
feat(dev): add startup profiling for cold-start diagnosis (#28566)
Yash Singh committed
Nov 1, 2026 at 03:56 UTC
0bc95fcdea918e2d155c53ab21e5beefdaa59733
11 files changed
+715
-19
apps/server/src/bin.ts
+4
@@ -40,7 +40,11 @@ if (
40
// Windows desktop launches without stdin; attach before reading, except on fast paths using pipes.
41
const { attachConsoleStdin } = await import("./cli/consoleStdin.ts");
42
attachConsoleStdin();
43
+ const importStart = performance.now();
44
const { runCli } = await import("./binCli.ts");
45
+ if (process.env.T3CODE_STARTUP_PROFILE_DIR) {
46
+ performance.measure("server.import.binCli", { start: importStart });
47
+ }
48
runCli();
49
}
50
}
apps/server/src/persistence/Sqlite.ts
+1
-1
@@ -41,7 +41,7 @@ const layerSetup = Layer.effectDiscard(
41
yield* sql`DELETE FROM sqlite_stat1;`;
42
yield* sql`ANALYZE sqlite_schema;`;
43
}
44
- }),
44
+ }).pipe(Effect.withSpan("Sqlite.setup")),
45
);
46
47
export const layerFromPath = Effect.fn("makeSqlitePersistenceLive")(function* (dbPath: string) {
apps/server/src/ws.test.ts
+50
-12
@@ -21,6 +21,7 @@ import {
21
import * as Deferred from "effect/Deferred";
22
import * as DateTime from "effect/DateTime";
23
import * as Effect from "effect/Effect";
24
+import * as Fiber from "effect/Fiber";
25
import * as Layer from "effect/Layer";
26
import * as PubSub from "effect/PubSub";
27
import * as Queue from "effect/Queue";
@@ -127,7 +128,7 @@ import {
128
subscribeOrchestrationV2Shell,
129
subscribeOrchestrationV2Thread,
130
WS_RPC_SERVER_OPTIONS,
130
- withLateEditorConfig,
131
+ withLateConfigDiscovery,
132
} from "./ws.ts";
133
134
const snapshotConfig = (fields: Partial<ServerConfig>) =>
@@ -142,7 +143,7 @@ const settingsUpdated = (settings: object): ServerConfigStreamEvent => ({
143
it.effect("resends late editors without rolling back updates already sent", () =>
144
Effect.gen(function* () {
145
const settingsSent = yield* Deferred.make<void>();
145
- const events = yield* withLateEditorConfig(
146
+ const events = yield* withLateConfigDiscovery(
147
snapshotConfig({ settings: { enableProviderUpdateChecks: true } as never }),
148
Stream.make(settingsUpdated({ enableProviderUpdateChecks: false })),
149
{
@@ -150,6 +151,7 @@ it.effect("resends late editors without rolling back updates already sent", () =
151
resolveFileManagerRevealKind: () =>
152
Deferred.await(settingsSent).pipe(Effect.as("file-explorer" as const)),
153
},
154
+ { resolveTargets: () => Effect.succeed([]) },
155
).pipe(
156
Stream.tap((event) =>
157
event.type === "settingsUpdated" ? Deferred.succeed(settingsSent, undefined) : Effect.void,
@@ -169,24 +171,35 @@ it.effect("resends late editors without rolling back updates already sent", () =
171
}),
172
);
173
172
-it.effect("resends a file manager reveal kind that missed the snapshot", () =>
174
+it.effect("resends a reveal kind and remote targets that outlast the snapshot timeout", () =>
175
Effect.gen(function* () {
174
- const events = yield* withLateEditorConfig(
176
+ const targets = [{ kind: "mdns" as const, host: "test.local" }];
177
+ const finishDiscovery = yield* Deferred.make<typeof targets>();
178
+ const collecting = yield* withLateConfigDiscovery(
179
snapshotConfig({ availableEditors: ["file-manager"] }),
180
Stream.empty,
181
{
182
resolveAvailableEditors: () => Effect.succeed(["file-manager"]),
183
resolveFileManagerRevealKind: () => Effect.succeed("file-explorer"),
184
},
181
- ).pipe(Stream.runCollect);
185
+ { resolveTargets: () => Deferred.await(finishDiscovery) },
186
+ ).pipe(Stream.runCollect, Effect.forkScoped({ startImmediately: true }));
187
+ yield* TestClock.adjust("6 seconds");
188
+ yield* Deferred.succeed(finishDiscovery, targets);
189
+ const events = yield* Fiber.join(collecting);
190
183
- const [late] = Array.from(events);
184
- assert.equal(events.length, 1);
191
+ const [late, remote] = Array.from(events);
192
+ assert.equal(events.length, 2);
193
assert.equal(late?.type, "snapshot");
194
if (late?.type === "snapshot") {
195
assert.equal(late.config.shellRevealInFileManagerKind, "file-explorer");
196
}
189
- }),
197
+ assert.equal(remote?.type, "snapshot");
198
+ if (remote?.type === "snapshot") {
199
+ assert.deepEqual(remote.config.remoteOpenTargets, targets);
200
+ assert.equal(remote.config.shellRevealInFileManagerKind, "file-explorer");
201
+ }
202
+ }).pipe(Effect.scoped),
203
);
204
205
it.effect("runs editor, remote open target and direct endpoint discovery side by side", () =>
@@ -600,9 +613,9 @@ const layerConfigSources = Layer.mergeAll(
613
Layer.provideMerge(NodeServices.layer),
614
);
615
603
-it.effect(
604
- "preserves settings during discovery and keybindings during snapshot ACK at the config RPC boundary",
605
- () =>
616
+it.effect.each(["pending", "cached"] as const)(
617
+ "%s remote discovery preserves initial config and updates through discovery and ACK",
618
+ (discovery) =>
619
Effect.gen(function* () {
620
const keybindings = yield* Keybindings.Keybindings;
621
const settings = yield* ServerSettings.ServerSettingsService;
@@ -617,6 +630,9 @@ it.effect(
630
const initialKeybindings = (yield* keybindings.getSnapshot).keybindings;
631
const discoveryStarted = yield* Deferred.make<void>();
632
const finishDiscovery = yield* Deferred.make<void>();
633
+ const remoteDiscoveryStarted = yield* Deferred.make<void>();
634
+ const finishRemoteDiscovery = yield* Deferred.make<void>();
635
+ const targets = [{ kind: "mdns" as const, host: "test.local" }];
636
const responses = yield* Queue.unbounded<ServerConfigStreamEvent>();
637
const configRpcServices = Layer.mergeAll(
638
layerUnusedConfigRpcServices,
@@ -635,7 +651,13 @@ it.effect(
651
}),
652
Layer.mock(UsageLimitSources.UsageLimitSources)({ streamChanges: Stream.make([]) }),
653
Layer.mock(RemoteOpenTargets.RemoteOpenTargets)({
638
- resolveTargets: () => Effect.succeed([]),
654
+ resolveTargets: () =>
655
+ Deferred.succeed(remoteDiscoveryStarted, undefined).pipe(
656
+ Effect.andThen(
657
+ discovery === "cached" ? Effect.void : Deferred.await(finishRemoteDiscovery),
658
+ ),
659
+ Effect.as(targets),
660
+ ),
661
}),
662
Layer.mock(DirectEndpoints.DirectEndpoints)({ resolve: () => Effect.succeed([]) }),
663
Layer.mock(ManagedProjectFolders.ManagedProjectFolders)({
@@ -710,12 +732,14 @@ it.effect(
732
headers: Headers.empty,
733
});
734
yield* Deferred.await(discoveryStarted);
735
+ assert.isTrue(yield* Deferred.isDone(remoteDiscoveryStarted));
736
737
const duringDiscovery = yield* settings.updateSettings({ defaultAutoPull: true });
738
yield* Deferred.succeed(finishDiscovery, undefined);
739
const snapshot = yield* Queue.take(responses);
740
assert.equal(snapshot.type, "snapshot");
741
if (snapshot.type !== "snapshot") return yield* Effect.die("Missing initial snapshot");
742
+ assert.deepEqual(snapshot.config.remoteOpenTargets, discovery === "cached" ? targets : []);
743
assert.isFalse(snapshot.config.settings.defaultAutoPull);
744
assert.deepEqual(snapshot.config.keybindings, initialKeybindings);
745
const duringAck = yield* keybindings.upsertKeybindingRule({
@@ -752,6 +776,20 @@ it.effect(
776
}
777
assert.isEmpty(expectedSettings);
778
assert.isEmpty(expectedKeybindings);
779
+ if (discovery === "pending") {
780
+ yield* Deferred.await(remoteDiscoveryStarted);
781
+ yield* Deferred.succeed(finishRemoteDiscovery, undefined);
782
+ const resolved = yield* Queue.take(responses);
783
+ assert.equal(resolved.type, "snapshot");
784
+ if (resolved.type !== "snapshot") return yield* Effect.die("Missing remote targets");
785
+ assert.deepEqual(resolved.config.remoteOpenTargets, targets);
786
+ assert.deepEqual(
787
+ resolved.config.settings,
788
+ ServerSettings.redactServerSettingsForClient(latestSettings),
789
+ );
790
+ assert.deepEqual(resolved.config.keybindings, latestKeybindings);
791
+ yield* acknowledge;
792
+ }
793
yield* server.write(0, { _tag: "Interrupt", requestId, interruptors: [] });
794
}).pipe(
795
Effect.provide(
apps/server/src/ws.ts
+39
-6
@@ -9,6 +9,7 @@ import * as DateTime from "effect/DateTime";
9
import * as Duration from "effect/Duration";
10
import * as Base64 from "effect/encoding/Base64";
11
import * as Effect from "effect/Effect";
12
+import * as Fiber from "effect/Fiber";
13
import * as FileSystem from "effect/FileSystem";
14
import * as Layer from "effect/Layer";
15
import * as Option from "effect/Option";
@@ -313,10 +314,11 @@ const resolveEditorConfig = Effect.fn("ws.resolveEditorConfig")(function* <E, R>
314
};
315
});
316
316
-export const withLateEditorConfig = <E, R>(
317
+export const withLateConfigDiscovery = <E, R>(
318
config: ClientServerConfig,
319
liveUpdates: Stream.Stream<ServerConfigStreamEvent, E, R>,
320
launcher: EditorDiscovery,
321
+ remoteOpenTargets: RemoteOpenTargets.RemoteOpenTargets["Service"],
322
) => {
323
const lateEditorConfig = Stream.fromEffect(launcher.resolveAvailableEditors()).pipe(
324
Stream.filter(
@@ -337,7 +339,14 @@ export const withLateEditorConfig = <E, R>(
339
Stream.map((editorConfig) => ({ type: "editorsResolved" as const, editorConfig })),
340
);
341
340
- return Stream.merge(liveUpdates, lateEditorConfig).pipe(
342
+ const lateRemoteOpenTargets = Stream.fromEffect(remoteOpenTargets.resolveTargets()).pipe(
343
+ Stream.filter(
344
+ (targets) => JSON.stringify(targets) !== JSON.stringify(config.remoteOpenTargets ?? []),
345
+ ),
346
+ Stream.map((targets) => ({ type: "remoteOpenTargetsResolved" as const, targets })),
347
+ );
348
+
349
+ return Stream.merge(liveUpdates, Stream.merge(lateEditorConfig, lateRemoteOpenTargets)).pipe(
350
Stream.mapAccum(
351
(): ClientServerConfig => config,
352
(current, event): readonly [ClientServerConfig, ReadonlyArray<ServerConfigStreamEvent>] => {
@@ -352,6 +361,10 @@ export const withLateEditorConfig = <E, R>(
361
const next = { ...rest, ...event.editorConfig };
362
return [next, [{ version: 1, type: "snapshot", config: next }]];
363
}
364
+ case "remoteOpenTargetsResolved": {
365
+ const next = { ...current, remoteOpenTargets: event.targets };
366
+ return [next, [{ version: 1, type: "snapshot", config: next }]];
367
+ }
368
case "keybindingsUpdated":
369
return [{ ...current, ...event.payload }, [event]];
370
case "providerStatuses":
@@ -1754,6 +1767,7 @@ export const layerWsRpc = (
1767
const loadServerConfig = Effect.fn("ws.loadServerConfig")(function* (options: {
1768
readonly usageLimitsCommand: boolean;
1769
readonly workspaceSnapshotsOnDemand: boolean;
1770
+ readonly deferRemoteOpenTargets: boolean;
1771
}) {
1772
const keybindingsConfig = yield* keybindings.loadConfigState;
1773
const currentProviders = yield* providerRegistry.getProviders;
@@ -1773,7 +1787,9 @@ export const layerWsRpc = (
1787
const discovery = yield* resolveOpenDiscoveryForConfig({
1788
editors: externalLauncher.resolveAvailableEditors(),
1789
fileManagerRevealKind: externalLauncher.resolveFileManagerRevealKind(),
1776
- remoteOpenTargets: remoteOpenTargets.resolveTargets(),
1790
+ remoteOpenTargets: options.deferRemoteOpenTargets
1791
+ ? Effect.succeed([])
1792
+ : remoteOpenTargets.resolveTargets(),
1793
directEndpoints: directEndpoints.resolve(),
1794
});
1795
@@ -2203,7 +2219,11 @@ export const layerWsRpc = (
2219
),
2220
[WS_METHODS.serverProbe]: (_input) => Effect.succeed({}),
2221
[WS_METHODS.serverGetConfig]: (_input) =>
2206
- loadServerConfig({ usageLimitsCommand: false, workspaceSnapshotsOnDemand: false }),
2222
+ loadServerConfig({
2223
+ usageLimitsCommand: false,
2224
+ workspaceSnapshotsOnDemand: false,
2225
+ deferRemoteOpenTargets: false,
2226
+ }),
2227
[WS_METHODS.serverSearchAcpRegistry]: (input) =>
2228
acpRegistryCatalog
2229
.search(input)
@@ -3126,9 +3146,13 @@ export const layerWsRpc = (
3146
// Buffer changes through discovery and the initial snapshot's RPC ACK wait.
3147
const keybindingsChanges = yield* keybindings.subscribeChanges;
3148
const settingsChanges = yield* serverSettings.subscribeChanges;
3149
+ const remoteTargets = yield* Effect.forkScoped(remoteOpenTargets.resolveTargets(), {
3150
+ startImmediately: true,
3151
+ });
3152
const config = yield* loadServerConfig({
3153
usageLimitsCommand,
3154
workspaceSnapshotsOnDemand,
3155
+ deferRemoteOpenTargets: true,
3156
});
3157
const keybindingsUpdates = keybindingsChanges.pipe(
3158
Stream.map((event) => ({
@@ -3215,9 +3239,18 @@ export const layerWsRpc = (
3239
),
3240
);
3241
3242
+ const remoteResult = yield* Effect.sync(() => remoteTargets.pollUnsafe());
3243
+ const initialConfig =
3244
+ remoteResult?._tag === "Success"
3245
+ ? { ...config, remoteOpenTargets: remoteResult.value }
3246
+ : config;
3247
return Stream.concat(
3219
- rpcInitialItems([{ version: 1 as const, type: "snapshot" as const, config }]),
3220
- withLateEditorConfig(config, liveUpdates, externalLauncher),
3248
+ rpcInitialItems([
3249
+ { version: 1 as const, type: "snapshot" as const, config: initialConfig },
3250
+ ]),
3251
+ withLateConfigDiscovery(initialConfig, liveUpdates, externalLauncher, {
3252
+ resolveTargets: () => Fiber.join(remoteTargets),
3253
+ }),
3254
);
3255
}),
3256
),
apps/web/scripts/warm-dep-cache.ts
+8
@@ -10,6 +10,14 @@ import { optimizeDeps, resolveConfig } from "vite";
10
11
const webRoot = NodePath.dirname(NodePath.dirname(NodeURL.fileURLToPath(import.meta.url)));
12
13
+const configStart = performance.now();
14
const config = await resolveConfig({ root: webRoot, logLevel: "error" }, "serve");
15
+if (process.env.T3CODE_STARTUP_PROFILE_DIR) {
16
+ performance.measure("web.warmDepCache.resolveConfig", { start: configStart });
17
+}
18
+const optimizeStart = performance.now();
19
await optimizeDeps(config);
20
+if (process.env.T3CODE_STARTUP_PROFILE_DIR) {
21
+ performance.measure("web.warmDepCache.optimizeDeps", { start: optimizeStart });
22
+}
23
console.log("[warm-dep-cache] web dependency cache is warm");
docs/operations/development.md
+28
@@ -86,6 +86,34 @@ To add a scenario, point a `SCENARIOS` entry at a generic ACP replay fixture
86
The agent replays session updates, permission requests, and questions. It drops session setup
87
and vendor frames, so Grok and fx recordings lose their vendor-only behavior.
88
89
+### Profiling dev startup
90
+
91
+Run `vp run profile:startup` to capture the first 20 seconds of inherited Node processes under
92
+`.t3/startup-profiles/<timestamp>`. Workers that execute the preload get separate profiles.
93
+It starts the normal dev runner and accepts its flags.
94
+Stop it with Ctrl+C after the capture. Set `T3CODE_STARTUP_PROFILE_DIR` to choose another output
95
+directory. Profiling adds overhead, so compare readiness with an ordinary `vp run dev` run.
96
+
97
+Open a `.cpuprofile` in Chrome DevTools' Performance panel for sampled function stacks and source
98
+lines. Each `.modules.json` is a Chrome trace containing timed module resolution, loading,
99
+synchronous subprocess calls, and startup measures. Per-file records include importer URLs,
100
+source loading, preparation, recursive dependency linking, and top-level evaluation. Preparation
101
+uses synchronous loader boundaries; linking includes dependencies, and CommonJS evaluation can
102
+include nested `require` calls. Some ESM/CommonJS interop reports a combined stage. `.process.json` records the process, Node version, and capture window.
103
+The server's nested Effect and SQL spans remain in `.t3/userdata/logs/server.trace.ndjson`.
104
+
105
+The preload temporarily adds module-body timing markers and uses one automatic debugger pause
106
+to instrument the live Node loader. The launcher adds `--no-node-snapshot` to inherited
107
+`NODE_OPTIONS` because Node 26's snapshotted loader cannot accept that breakpoint. Include the
108
+same flag when using the preload directly. This disables Node's built-in startup snapshot,
109
+can change compilation-cache hits, and adds overhead.
110
+Treat per-file captures as diagnostic runs; use uninstrumented runs for baseline startup latency.
111
+The first entry module can compile before loader instrumentation is installed.
112
+
113
+A fresh process still uses filesystem, Node compilation, provider, and Vite dependency caches.
114
+Measure a missing Vite dependency cache separately from a restart with an existing database.
115
+Neither the Vite ready message nor the HTTP listener proves that a browser has rendered the app.
116
+
117
### Sharing and remote debugging
118
119
`vp run dev --share` publishes the web port over the machine's tailnet and prints a pairing URL
package.json
+1
@@ -5,6 +5,7 @@
5
"scripts": {
6
"prepare": "vp config --no-agent",
7
"dev": "node scripts/dev-runner.ts dev",
8
+ "profile:startup": "node scripts/profile-startup.mjs",
9
"dev:share": "node scripts/dev-runner.ts dev --share",
10
"dev:server": "node scripts/dev-runner.ts dev:server",
11
"dev:web": "node scripts/dev-runner.ts dev:web",
packages/provider-cursor/src/server/sdk.ts
+8
@@ -3,6 +3,7 @@ import * as NodeModule from "node:module";
3
4
// createRequire loads the disk-backed SDK and adjacent chunks even from a Node SEA executable.
5
const requireCursorSdk = NodeModule.createRequire(import.meta.url);
6
+const sdkImportStart = performance.now();
7
export const {
8
Agent,
9
AuthenticationError,
@@ -12,6 +13,13 @@ export const {
13
CursorSdkError,
14
InMemoryCredentialStore,
15
} = requireCursorSdk("@cursor/sdk") as typeof import("@cursor/sdk");
16
+if (process.env.T3CODE_STARTUP_PROFILE_DIR) {
17
+ performance.measure("provider.cursor.importSdk", { start: sdkImportStart });
18
+}
19
+const sqliteImportStart = performance.now();
20
export const { SqliteLocalAgentStore } = requireCursorSdk(
21
"@cursor/sdk/sqlite",
22
) as typeof import("@cursor/sdk/sqlite");
23
+if (process.env.T3CODE_STARTUP_PROFILE_DIR) {
24
+ performance.measure("provider.cursor.importSqliteStore", { start: sqliteImportStart });
25
+}
scripts/profile-startup-modules.mjs
new
+262
@@ -0,0 +1,262 @@
1
+import * as NodeFS from "node:fs";
2
+import * as NodeModule from "node:module";
3
+import * as NodePerfHooks from "node:perf_hooks";
4
+import * as NodeURL from "node:url";
5
+
6
+export function profileStartupModules(session, events, threadId) {
7
+ const now = () => NodePerfHooks.performance.now();
8
+ const origin = NodePerfHooks.performance.timeOrigin;
9
+ const loaded = new Map();
10
+ const compiling = new Map();
11
+ const evaluating = new Map();
12
+ const registryKey = "__t3codeStartupModuleProfiler";
13
+ const previousRegistry = globalThis[registryKey];
14
+ const previousModuleRegistry = NodeModule.default[registryKey];
15
+ const restorers = [];
16
+ let active = true;
17
+ let installed = false;
18
+ let breakpoint;
19
+ let currentLink;
20
+ let nextLink = 0;
21
+
22
+ const record = (stage, url, start, end, attributes = {}) => {
23
+ if (!active) return;
24
+ events.push({
25
+ name: `${stage} ${url}`,
26
+ cat: "module.detail",
27
+ ph: "X",
28
+ pid: process.pid,
29
+ tid: threadId,
30
+ ts: (origin + start) * 1000,
31
+ dur: (end - start) * 1000,
32
+ args: { stage, url, ...attributes },
33
+ });
34
+ };
35
+ const toUrl = (file) =>
36
+ file instanceof URL
37
+ ? file.href
38
+ : typeof file === "string"
39
+ ? file.startsWith("file:")
40
+ ? file
41
+ : NodeURL.pathToFileURL(file).href
42
+ : undefined;
43
+ const inject = (source, statement, preserveDirectives) => {
44
+ let offset = source.startsWith("#!") ? source.indexOf("\n") + 1 : 0;
45
+ if (preserveDirectives) {
46
+ for (;;) {
47
+ const trivia = /^(?:\s+|\/\/[^\n]*(?:\n|$)|\/\*[\s\S]*?\*\/)*/.exec(
48
+ source.slice(offset),
49
+ )[0];
50
+ offset += trivia.length;
51
+ if (!/^["']/.test(source.slice(offset))) break;
52
+ const directive = /^(?:"(?:\\.|[^"\\\r\n])*"|'(?:\\.|[^'\\\r\n])*')\s*;/.exec(
53
+ source.slice(offset),
54
+ );
55
+ // Leave ambiguous semicolon-free prologues untouched rather than changing strict-mode semantics.
56
+ if (!directive) return undefined;
57
+ offset += directive[0].length;
58
+ }
59
+ }
60
+ return source.slice(0, offset) + statement + source.slice(offset);
61
+ };
62
+ const registry = {
63
+ begin(url) {
64
+ if (active) evaluating.set(url, now());
65
+ },
66
+ end(url) {
67
+ const start = evaluating.get(url);
68
+ if (start === undefined) return;
69
+ record("evaluate", url, start, now(), {
70
+ format: "esm",
71
+ boundary: "module body; top-level await included",
72
+ });
73
+ evaluating.delete(url);
74
+ },
75
+ cjsBegin(filename) {
76
+ const url = toUrl(filename),
77
+ pending = compiling.get(url);
78
+ if (!pending) return;
79
+ pending.evaluationStart = now();
80
+ record("prepare", url, pending.start, pending.evaluationStart, {
81
+ format: "commonjs",
82
+ boundary: "_compile entry to module-body entry",
83
+ });
84
+ },
85
+ install(job) {
86
+ if (installed) return;
87
+ installed = true;
88
+ const loader = Object.getPrototypeOf(job.loader);
89
+ for (const method of [
90
+ "loadAndTranslate",
91
+ "loadAndTranslateForRequireInImportedCJS",
92
+ "loadAndTranslateForImportInRequiredESM",
93
+ ]) {
94
+ const original = loader[method];
95
+ if (typeof original !== "function") continue;
96
+ loader[method] = function (url, ...args) {
97
+ const start = now();
98
+ try {
99
+ return original.call(this, url, ...args);
100
+ } finally {
101
+ const moduleUrl = typeof url === "string" ? url : url.url;
102
+ const pending = loaded.get(moduleUrl);
103
+ if (pending && pending.start >= start)
104
+ record("prepare", moduleUrl, pending.start, now(), {
105
+ format: pending.format,
106
+ boundary:
107
+ "source-ready to loadAndTranslate return; compilation and format preparation",
108
+ });
109
+ }
110
+ };
111
+ restorers.push(() => {
112
+ loader[method] = original;
113
+ });
114
+ }
115
+ const prototype = Object.getPrototypeOf(Object.getPrototypeOf(job)),
116
+ link = prototype.syncLink;
117
+ prototype.syncLink = function (...args) {
118
+ const start = now(),
119
+ parent = currentLink,
120
+ id = ++nextLink;
121
+ currentLink = { id, url: this.url };
122
+ try {
123
+ return link.apply(this, args);
124
+ } finally {
125
+ record("link", this.url, start, now(), {
126
+ id,
127
+ parentId: parent?.id,
128
+ importedBy: parent?.url,
129
+ boundary: "ModuleJob.syncLink; includes recursive dependency loading",
130
+ });
131
+ currentLink = parent;
132
+ }
133
+ };
134
+ restorers.push(() => {
135
+ prototype.syncLink = link;
136
+ });
137
+ },
138
+ };
139
+ globalThis[registryKey] = registry;
140
+ NodeModule.default[registryKey] = registry;
141
+
142
+ session.post("Debugger.enable");
143
+ // One pause obtains the live loader; subsequent measurements use synchronous method boundaries.
144
+ const source = process.binding("natives")["internal/modules/esm/module_job"].split("\n");
145
+ const classLine = source.findIndex((line) => line.includes("class ModuleJob extends"));
146
+ const lineNumber = source.findIndex(
147
+ (line, index) => index > classLine && line.includes("this.linked = this.link("),
148
+ );
149
+ const paused = ({ params }) => {
150
+ if (!breakpoint || !params.hitBreakpoints?.includes(breakpoint)) return;
151
+ const start = now();
152
+ session.post("Debugger.removeBreakpoint", { breakpointId: breakpoint });
153
+ breakpoint = undefined;
154
+ session.post(
155
+ "Debugger.evaluateOnCallFrame",
156
+ {
157
+ callFrameId: params.callFrames[0].callFrameId,
158
+ expression: `globalThis.${registryKey}.install(this)`,
159
+ silent: true,
160
+ },
161
+ (error, result) => {
162
+ if (error || result?.exceptionDetails)
163
+ record("instrumentation-error", "node:esm-loader", start, now());
164
+ },
165
+ );
166
+ record("instrumentation-setup", "node:esm-loader", start, now());
167
+ session.post("Debugger.resume");
168
+ };
169
+ session.on("Debugger.paused", paused);
170
+ if (lineNumber >= 0)
171
+ session.post(
172
+ "Debugger.setBreakpointByUrl",
173
+ {
174
+ url: "node:internal/modules/esm/module_job",
175
+ lineNumber,
176
+ },
177
+ (error, result) => {
178
+ if (!error) breakpoint = result.breakpointId;
179
+ },
180
+ );
181
+
182
+ const readFileSync = NodeFS.default.readFileSync;
183
+ NodeFS.default.readFileSync = function (file, ...args) {
184
+ const url = toUrl(file);
185
+ if (!url || !/\.[cm]?[jt]sx?(?:$|\?)/.test(url)) return readFileSync.call(this, file, ...args);
186
+ const start = now();
187
+ try {
188
+ return readFileSync.call(this, file, ...args);
189
+ } finally {
190
+ record("read", url, start, now());
191
+ }
192
+ };
193
+ const compile = NodeModule.default.prototype._compile;
194
+ NodeModule.default.prototype._compile = function (source, filename, ...args) {
195
+ const url = toUrl(filename),
196
+ pending = { start: now() };
197
+ const format = args[0] ?? loaded.get(url)?.format;
198
+ const isEsm =
199
+ format === "module" ||
200
+ format === "module-typescript" ||
201
+ /(^|[;\n])\s*(?:import[\s.]|export\s)/.test(source);
202
+ const annotated = isEsm
203
+ ? undefined
204
+ : inject(source, `module.constructor.${registryKey}?.cjsBegin(__filename);`, true);
205
+ compiling.set(url, pending);
206
+ try {
207
+ return compile.call(this, annotated ?? source, filename, ...args);
208
+ } finally {
209
+ const end = now();
210
+ record(isEsm ? "require-esm" : "commonjs", url, pending.start, end, {
211
+ importedBy: this.parent?.filename ? toUrl(this.parent.filename) : undefined,
212
+ sourceBytes: Buffer.byteLength(source),
213
+ });
214
+ if (pending.evaluationStart !== undefined)
215
+ record("evaluate", url, pending.evaluationStart, end, {
216
+ format: "commonjs",
217
+ includesNestedRequires: true,
218
+ });
219
+ compiling.delete(url);
220
+ }
221
+ };
222
+ NodeModule.syncBuiltinESMExports();
223
+
224
+ return {
225
+ sourceReady(url, result) {
226
+ if (!url.startsWith("file:")) return result;
227
+ const format = result.format;
228
+ let source = result.source;
229
+ if (typeof source !== "string" && ArrayBuffer.isView(source))
230
+ source = Buffer.from(source.buffer, source.byteOffset, source.byteLength).toString("utf8");
231
+ if (typeof source === "string" && (format === "module" || format === "module-typescript")) {
232
+ // A module-local globalThis binding would put the injected access in its temporal dead zone.
233
+ if (!/\b(?:const|let|var|class|function|as)\s+globalThis\b/.test(source)) {
234
+ source =
235
+ inject(source, `globalThis.${registryKey}?.begin(import.meta.url);`, false) +
236
+ `\n;globalThis.${registryKey}?.end(import.meta.url);\n`;
237
+ result = { ...result, source };
238
+ }
239
+ }
240
+ loaded.set(url, { start: now(), format });
241
+ return result;
242
+ },
243
+ finish() {
244
+ const end = now();
245
+ for (const [url, start] of evaluating)
246
+ record("evaluate", url, start, end, { incomplete: true });
247
+ record("instrumentation-status", "node:esm-loader", end, end, { installed });
248
+ active = false;
249
+ if (breakpoint) session.post("Debugger.removeBreakpoint", { breakpointId: breakpoint });
250
+ session.off("Debugger.paused", paused);
251
+ session.post("Debugger.disable");
252
+ for (const restore of restorers.reverse()) restore();
253
+ NodeFS.default.readFileSync = readFileSync;
254
+ NodeModule.default.prototype._compile = compile;
255
+ NodeModule.syncBuiltinESMExports();
256
+ if (previousRegistry === undefined) delete globalThis[registryKey];
257
+ else globalThis[registryKey] = previousRegistry;
258
+ if (previousModuleRegistry === undefined) delete NodeModule.default[registryKey];
259
+ else NodeModule.default[registryKey] = previousModuleRegistry;
260
+ },
261
+ };
262
+}
scripts/profile-startup.mjs
new
+165
@@ -0,0 +1,165 @@
1
+// Opt in with T3CODE_STARTUP_PROFILE_DIR=/absolute/path NODE_OPTIONS="--no-node-snapshot --import=/absolute/path/to/this/file".
2
+import * as NodeFS from "node:fs";
3
+import * as NodeInspector from "node:inspector";
4
+import * as NodeChildProcess from "node:child_process";
5
+import * as NodeModule from "node:module";
6
+import * as NodePath from "node:path";
7
+import * as NodePerfHooks from "node:perf_hooks";
8
+import * as NodeWorkerThreads from "node:worker_threads";
9
+import * as NodeURL from "node:url";
10
+
11
+import { profileStartupModules } from "./profile-startup-modules.mjs";
12
+
13
+const directory = process.env.T3CODE_STARTUP_PROFILE_DIR;
14
+const isLauncher = process.argv[1] === NodeURL.fileURLToPath(import.meta.url);
15
+if (directory && !isLauncher) {
16
+ NodeFS.mkdirSync(directory, { recursive: true });
17
+ const { threadId } = NodeWorkerThreads;
18
+ const prefix = NodePath.join(directory, `${process.pid}-${threadId}`);
19
+ const origin = NodePerfHooks.performance.timeOrigin;
20
+ const events = [];
21
+ const session = new NodeInspector.Session();
22
+ session.connect();
23
+ session.post("Profiler.setSamplingInterval", { interval: 1000 });
24
+ session.post("Profiler.enable");
25
+ const profileStartTimeUnixMs = origin + NodePerfHooks.performance.now();
26
+ session.post("Profiler.start");
27
+
28
+ const moduleDetails = profileStartupModules(session, events, threadId);
29
+
30
+ const measure = (name, operation, cat = "module", attributes = {}) => {
31
+ const start = NodePerfHooks.performance.now();
32
+ try {
33
+ return operation();
34
+ } finally {
35
+ events.push({
36
+ name,
37
+ cat,
38
+ ph: "X",
39
+ pid: process.pid,
40
+ tid: threadId,
41
+ ts: (origin + start) * 1000,
42
+ dur: (NodePerfHooks.performance.now() - start) * 1000,
43
+ args: attributes,
44
+ });
45
+ }
46
+ };
47
+
48
+ const recordMeasures = (entries) => {
49
+ for (const entry of entries) {
50
+ events.push({
51
+ name: entry.name,
52
+ cat: "startup",
53
+ ph: "X",
54
+ pid: process.pid,
55
+ tid: threadId,
56
+ ts: (origin + entry.startTime) * 1000,
57
+ dur: entry.duration * 1000,
58
+ });
59
+ }
60
+ };
61
+ const observer = new NodePerfHooks.PerformanceObserver((list) =>
62
+ recordMeasures(list.getEntries()),
63
+ );
64
+ observer.observe({ entryTypes: ["measure"] });
65
+ const execFileSync = NodeChildProcess.default.execFileSync;
66
+ NodeChildProcess.default.execFileSync = function (file, ...args) {
67
+ return measure(
68
+ `execFileSync ${file}`,
69
+ () => execFileSync.call(this, file, ...args),
70
+ "subprocess",
71
+ );
72
+ };
73
+ NodeModule.syncBuiltinESMExports();
74
+
75
+ const hooks = NodeModule.registerHooks({
76
+ resolve(specifier, context, next) {
77
+ const attributes = { specifier, parentURL: context.parentURL };
78
+ return measure(
79
+ `resolve ${specifier}`,
80
+ () => {
81
+ const result = next(specifier, context);
82
+ attributes.url = result.url;
83
+ attributes.format = result.format;
84
+ return result;
85
+ },
86
+ "module",
87
+ attributes,
88
+ );
89
+ },
90
+ load(url, context, next) {
91
+ const result = measure(`load ${url}`, () => next(url, context), "module", {
92
+ url,
93
+ format: context.format,
94
+ });
95
+ return moduleDetails.sourceReady(url, result);
96
+ },
97
+ });
98
+
99
+ let finished = false;
100
+ const finish = () => {
101
+ if (finished) return;
102
+ finished = true;
103
+ hooks.deregister();
104
+ moduleDetails.finish();
105
+ recordMeasures(observer.takeRecords());
106
+ observer.disconnect();
107
+ NodeChildProcess.default.execFileSync = execFileSync;
108
+ NodeModule.syncBuiltinESMExports();
109
+ session.post("Profiler.stop", (error, result) => {
110
+ if (!error) NodeFS.writeFileSync(`${prefix}.cpuprofile`, JSON.stringify(result.profile));
111
+ session.disconnect();
112
+ });
113
+ NodeFS.writeFileSync(`${prefix}.modules.json`, JSON.stringify({ traceEvents: events }));
114
+ NodeFS.writeFileSync(
115
+ `${prefix}.process.json`,
116
+ JSON.stringify({
117
+ pid: process.pid,
118
+ parentPid: process.ppid,
119
+ threadId,
120
+ nodeVersion: process.version,
121
+ executable: process.execPath,
122
+ entry: process.argv[1],
123
+ timeOrigin: origin,
124
+ profileStartTimeUnixMs,
125
+ captureEnd: origin + NodePerfHooks.performance.now(),
126
+ cpu: process.cpuUsage(),
127
+ memory: process.memoryUsage(),
128
+ }),
129
+ );
130
+ };
131
+ // Bound the capture without keeping dev servers or short-lived helpers alive.
132
+ setTimeout(finish, 20_000).unref();
133
+ process.once("exit", finish);
134
+}
135
+
136
+if (isLauncher) {
137
+ const output = NodePath.resolve(
138
+ directory ??
139
+ NodePath.join(".t3/startup-profiles", new Date().toISOString().replaceAll(":", "-")),
140
+ );
141
+ console.log(`[profile-startup] Writing CPU profiles and timeline events to ${output}`);
142
+ const child = NodeChildProcess.spawn(
143
+ process.execPath,
144
+ ["scripts/dev-runner.ts", "dev", ...process.argv.slice(2)],
145
+ {
146
+ stdio: "inherit",
147
+ env: {
148
+ ...process.env,
149
+ T3CODE_STARTUP_PROFILE_DIR: output,
150
+ // Node 26's snapshotted loader cannot accept the debugger breakpoint used by this profiler.
151
+ NODE_OPTIONS:
152
+ `${process.env.NODE_OPTIONS ?? ""} --no-node-snapshot --import=${import.meta.url}`.trim(),
153
+ },
154
+ },
155
+ );
156
+ process.on("SIGINT", () => child.kill("SIGINT"));
157
+ process.on("SIGTERM", () => child.kill("SIGTERM"));
158
+ child.on("error", (error) => {
159
+ console.error(error);
160
+ process.exitCode = 1;
161
+ });
162
+ child.on("exit", (code) => {
163
+ process.exitCode = code ?? 1;
164
+ });
165
+}
scripts/profile-startup.test.ts
new
+149
@@ -0,0 +1,149 @@
1
+// @effect-diagnostics nodeBuiltinImport:off -- Runs the profiling preload in a real Node subprocess.
2
+import * as NodeChildProcess from "node:child_process";
3
+import * as NodeFS from "node:fs";
4
+import * as NodeOS from "node:os";
5
+import * as NodePath from "node:path";
6
+import * as NodeURL from "node:url";
7
+import * as Schema from "effect/Schema";
8
+import { expect, it } from "vite-plus/test";
9
+
10
+const decodeTrace = Schema.decodeUnknownSync(
11
+ Schema.fromJsonString(
12
+ Schema.Struct({
13
+ traceEvents: Schema.Array(
14
+ Schema.Struct({
15
+ name: Schema.String,
16
+ ts: Schema.Number,
17
+ dur: Schema.Number,
18
+ args: Schema.optional(
19
+ Schema.Struct({
20
+ stage: Schema.optional(Schema.String),
21
+ url: Schema.optional(Schema.String),
22
+ parentURL: Schema.optional(Schema.String),
23
+ importedBy: Schema.optional(Schema.String),
24
+ installed: Schema.optional(Schema.Boolean),
25
+ }),
26
+ ),
27
+ }),
28
+ ),
29
+ }),
30
+ ),
31
+);
32
+
33
+const decodeRunner = Schema.decodeUnknownSync(
34
+ Schema.fromJsonString(Schema.Struct({ pid: Schema.Number, args: Schema.Array(Schema.String) })),
35
+);
36
+
37
+it("attributes ESM and CommonJS imports without changing module execution", () => {
38
+ const directory = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-startup-profile-"));
39
+ try {
40
+ NodeFS.writeFileSync(NodePath.join(directory, "package.json"), '{"type":"module"}');
41
+ const fixtures = {
42
+ "root.mjs": `
43
+ import { value } from './dependency.mjs';
44
+ import strict from './strict.cjs';
45
+ import loose from './loose.cjs';
46
+ import interop from './interop.cjs';
47
+ if (value !== 42 || strict !== undefined || loose !== true || interop !== 9) {
48
+ throw Error('Profiling changed module semantics');
49
+ }
50
+ `,
51
+ "dependency.mjs": "export const value = 42;",
52
+ "strict.cjs": `/* retain the directive */\n"use strict"; module.exports = (function () { return this; })();`,
53
+ "loose.cjs": "module.exports = (function () { return this; })() === globalThis;",
54
+ "interop.cjs": "module.exports = require('./required.js').value;",
55
+ "required.js": "export const value = 9;",
56
+ };
57
+ for (const [name, source] of Object.entries(fixtures)) {
58
+ NodeFS.writeFileSync(NodePath.join(directory, name), source);
59
+ }
60
+ const output = NodePath.join(directory, "capture");
61
+ const root = NodeURL.pathToFileURL(
62
+ NodeFS.realpathSync(NodePath.join(directory, "root.mjs")),
63
+ ).href;
64
+ NodeChildProcess.execFileSync(
65
+ process.execPath,
66
+ [
67
+ "--no-node-snapshot",
68
+ "--import",
69
+ NodeURL.pathToFileURL(NodePath.join(import.meta.dirname, "profile-startup.mjs")).href,
70
+ "--input-type=module",
71
+ "-e",
72
+ `await import(${JSON.stringify(root)})`,
73
+ ],
74
+ { env: { ...process.env, NODE_OPTIONS: "", T3CODE_STARTUP_PROFILE_DIR: output } },
75
+ );
76
+ const spans = NodeFS.readdirSync(output)
77
+ .filter((name) => name.endsWith(".modules.json"))
78
+ .flatMap(
79
+ (name) => decodeTrace(NodeFS.readFileSync(NodePath.join(output, name), "utf8")).traceEvents,
80
+ );
81
+ expect(spans.some((span) => span.args?.installed === true)).toBe(true);
82
+ for (const name of Object.keys(fixtures)) {
83
+ const url = NodeURL.pathToFileURL(NodeFS.realpathSync(NodePath.join(directory, name))).href;
84
+ const stages = spans.filter((span) => span.args?.url === url).map((span) => span.args?.stage);
85
+ expect(stages, name).toEqual(
86
+ expect.arrayContaining(
87
+ name === "required.js" ? ["link", "require-esm"] : ["prepare", "evaluate"],
88
+ ),
89
+ );
90
+ }
91
+ const prepared = spans.find(
92
+ (span) => span.args?.url === root && span.args?.stage === "prepare",
93
+ );
94
+ const linked = spans.find((span) => span.args?.url === root && span.args?.stage === "link");
95
+ if (!prepared || !linked) throw Error("Missing root module preparation/link boundaries");
96
+ expect(prepared.ts + prepared.dur).toBeLessThanOrEqual(linked.ts);
97
+ const dependency = NodeURL.pathToFileURL(
98
+ NodeFS.realpathSync(NodePath.join(directory, "dependency.mjs")),
99
+ ).href;
100
+ expect(
101
+ spans.find((span) => span.args?.url === dependency && span.args?.stage === "link")?.args
102
+ ?.importedBy,
103
+ ).toBe(root);
104
+ } finally {
105
+ NodeFS.rmSync(directory, { recursive: true, force: true });
106
+ }
107
+});
108
+
109
+it("captures only the dev runner and preserves its exit status", () => {
110
+ const directory = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-startup-launcher-"));
111
+ try {
112
+ NodeFS.mkdirSync(NodePath.join(directory, "scripts"));
113
+ NodeFS.writeFileSync(
114
+ NodePath.join(directory, "scripts/dev-runner.ts"),
115
+ "console.log(JSON.stringify({ pid: process.pid, args: process.argv.slice(2) }));",
116
+ );
117
+ const output = NodePath.join(directory, "capture");
118
+ const stdout = NodeChildProcess.execFileSync(
119
+ process.execPath,
120
+ [NodePath.join(import.meta.dirname, "profile-startup.mjs"), "--no-seed"],
121
+ {
122
+ cwd: directory,
123
+ env: { ...process.env, NODE_OPTIONS: "", T3CODE_STARTUP_PROFILE_DIR: output },
124
+ encoding: "utf8",
125
+ },
126
+ );
127
+ const runner = decodeRunner(stdout.trim().split("\n").at(-1));
128
+ expect(runner.args).toEqual(["dev", "--no-seed"]);
129
+ expect(NodeFS.readdirSync(output).sort()).toEqual(
130
+ ["cpuprofile", "modules.json", "process.json"].map((suffix) => `${runner.pid}-0.${suffix}`),
131
+ );
132
+ NodeFS.writeFileSync(
133
+ NodePath.join(directory, "scripts/dev-runner.ts"),
134
+ "process.kill(process.pid, 'SIGTERM');",
135
+ );
136
+ const interrupted = NodeChildProcess.spawnSync(
137
+ process.execPath,
138
+ [NodePath.join(import.meta.dirname, "profile-startup.mjs")],
139
+ {
140
+ cwd: directory,
141
+ env: { ...process.env, NODE_OPTIONS: "", T3CODE_STARTUP_PROFILE_DIR: output },
142
+ },
143
+ );
144
+ expect(interrupted.error).toBeUndefined();
145
+ expect(interrupted.status).toBe(1);
146
+ } finally {
147
+ NodeFS.rmSync(directory, { recursive: true, force: true });
148
+ }
149
+});