Skip to content

Commit af1caa2

Browse files
committed
fix(web): copy an update command that matches how the server is installed
The version-mismatch action hands every server that cannot update itself `npx t3@<client-version>`. For a server installed globally with npm, pnpm, or bun that command starts a second, throwaway copy instead of updating the executable the user restarts, and for a server launched through pnpm dlx or bunx it switches package runners. The server now reports how its CLI is installed in a new capabilities.serverInstall field, judged by where the resolved entry script lives: a package runner's cache (npx, pnpm dlx, bunx) or a package manager's global layout (npm, pnpm, bun). Project-local installs, repo checkouts, and the pinned service runtime report nothing. The field is only sent when serverSelfUpdate is absent, since those are the only servers that hand out a command, and clients decode unknown kinds as absent so a newer server cannot break an older client. Clients pick the command from that kind: a global install gets its package manager's upgrade command, a package runner is re-run at the target version, and servers that report nothing keep the npx relaunch. The user guide describes the command per install and keeps the explicit instruction to stop the running server first.
1 parent 18c5a1d commit af1caa2

12 files changed

Lines changed: 240 additions & 15 deletions

File tree

‎apps/server/src/cli/invocation.test.ts‎

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import { assert, it } from "@effect/vitest";
22

3-
import { formatCliCommand } from "./invocation.ts";
3+
import { detectServerInstall, formatCliCommand } from "./invocation.ts";
44

55
it("formats package runner commands from their cache entry paths", () => {
66
for (const [entryPath, expected] of [
@@ -43,6 +43,33 @@ it("treats stable installs as direct invocations", () => {
4343
}
4444
});
4545

46+
it("tells package runners, global installs, and everything else apart", () => {
47+
for (const [entryPath, expected] of [
48+
["/home/theo/.npm/_npx/abc123/node_modules/t3/dist/bin.mjs", "npx"],
49+
["/home/theo/.cache/pnpm/dlx/abc/node_modules/t3/dist/bin.mjs", "pnpm-dlx"],
50+
["/tmp/bunx-1000-t3@latest/node_modules/t3/dist/bin.mjs", "bunx"],
51+
["/usr/local/lib/node_modules/t3/dist/bin.mjs", "npm-global"],
52+
["/home/theo/.nvm/versions/node/v24.13.1/lib/node_modules/t3/dist/bin.mjs", "npm-global"],
53+
["C:\\Users\\theo\\AppData\\Roaming\\npm\\node_modules\\t3\\dist\\bin.mjs", "npm-global"],
54+
[
55+
"/home/theo/.local/share/pnpm/global/5/.pnpm/[email protected]/node_modules/t3/dist/bin.mjs",
56+
"pnpm-global",
57+
],
58+
["/home/theo/.bun/install/global/node_modules/t3/dist/bin.mjs", "bun-global"],
59+
] as const) {
60+
assert.equal(detectServerInstall(entryPath), expected);
61+
}
62+
// Nothing global updates these, so no command is suggested.
63+
for (const entryPath of [
64+
"/srv/project/node_modules/t3/dist/bin.mjs",
65+
"/home/theo/.t3/runtime/0.0.31/node_modules/t3/dist/bin.mjs",
66+
"/home/theo/Code/work/t3code/apps/server/dist/bin.mjs",
67+
"",
68+
]) {
69+
assert.isNull(detectServerInstall(entryPath));
70+
}
71+
});
72+
4673
it("re-suggests the nightly channel only for nightly builds", () => {
4774
for (const [version, expected] of [
4875
["0.0.31-nightly.20260729", "npx t3@nightly serve"],

‎apps/server/src/cli/invocation.ts‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import type { ServerInstallKind } from "@t3tools/contracts";
12
import * as Effect from "effect/Effect";
23

34
import { HostProcessArguments } from "@t3tools/shared/hostProcess";
@@ -36,6 +37,46 @@ function detectCliRunner(entryPath: string): CliRunner | null {
3637
return null;
3738
}
3839

40+
const SERVER_INSTALL_BY_RUNNER: Record<CliRunner, ServerInstallKind> = {
41+
npx: "npx",
42+
"pnpm dlx": "pnpm-dlx",
43+
bunx: "bunx",
44+
};
45+
46+
/**
47+
* How the CLI is installed, for clients that must tell the user how to update
48+
* it by hand. Package runners are recognised as above. Global installs are
49+
* recognised by each package manager's own layout, so the suggested command
50+
* is the one that manages that install:
51+
*
52+
* npm <prefix>/lib/node_modules/t3/... (system node, nvm, fnm, volta,
53+
* Homebrew), or %APPDATA%/npm/node_modules/t3/... on Windows
54+
* pnpm <pnpm home>/global/<n>/...
55+
* bun ~/.bun/install/global/...
56+
*
57+
* Pass the resolved entry script: the bin a global install runs is usually a
58+
* symlink into the package. Anything else (repo checkouts, project-local
59+
* installs, the pinned service runtime) returns null, since no global
60+
* command would update the executable that gets restarted.
61+
*/
62+
export function detectServerInstall(entryPath: string): ServerInstallKind | null {
63+
const runner = detectCliRunner(entryPath);
64+
if (runner !== null) {
65+
return SERVER_INSTALL_BY_RUNNER[runner];
66+
}
67+
const path = entryPath.replaceAll("\\", "/");
68+
if (path.includes("/pnpm/global/")) {
69+
return "pnpm-global";
70+
}
71+
if (path.includes("/.bun/install/global/")) {
72+
return "bun-global";
73+
}
74+
if (path.includes("/lib/node_modules/") || path.includes("/npm/node_modules/")) {
75+
return "npm-global";
76+
}
77+
return null;
78+
}
79+
3980
/**
4081
* The `t3` package spec to suggest. The literal spec the user typed (e.g.
4182
* `t3@nightly`) is resolved away before our process starts, so re-derive it

‎apps/server/src/environment/ServerEnvironment.test.ts‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import * as NodeServices from "@effect/platform-node/NodeServices";
22
import { expect, it } from "@effect/vitest";
3+
import { HostProcessArguments } from "@t3tools/shared/hostProcess";
34
import * as Crypto from "effect/Crypto";
45
import * as Deferred from "effect/Deferred";
56
import * as Effect from "effect/Effect";
@@ -260,6 +261,56 @@ it.layer(NodeServices.layer)("ServerEnvironmentLive", (it) => {
260261
}),
261262
);
262263

264+
it.effect("reports how the server is installed only when it cannot update itself", () =>
265+
Effect.gen(function* () {
266+
const fileSystem = yield* FileSystem.FileSystem;
267+
const baseDir = yield* fileSystem.makeTempDirectoryScoped({
268+
prefix: "t3-server-environment-install-test-",
269+
});
270+
const serverConfig = yield* makeServerConfig(baseDir);
271+
yield* fileSystem.makeDirectory(serverConfig.stateDir, { recursive: true });
272+
273+
const describeWith = (
274+
overrides: Partial<ServerConfig.ServerConfig["Service"]>,
275+
entryPath: string,
276+
) =>
277+
Effect.gen(function* () {
278+
const serverEnvironment = yield* ServerEnvironment.ServerEnvironment;
279+
return yield* serverEnvironment.getDescriptor;
280+
}).pipe(
281+
Effect.provide(
282+
ServerEnvironment.layer.pipe(
283+
Layer.provide(ServerSecretStore.layer),
284+
Layer.provide(ServerConfig.layer({ ...serverConfig, ...overrides })),
285+
Layer.provide(Layer.succeed(HostProcessArguments, ["/usr/bin/node", entryPath])),
286+
),
287+
),
288+
);
289+
290+
const npx = yield* describeWith({}, "/home/theo/.npm/_npx/abc/node_modules/t3/dist/bin.mjs");
291+
expect(npx.capabilities.serverSelfUpdate).toBeUndefined();
292+
expect(npx.capabilities.serverInstall).toBe("npx");
293+
294+
// A global install runs through a bin symlink; the install is read off
295+
// the package it points into.
296+
const packageDir = `${baseDir}/lib/node_modules/t3/dist`;
297+
yield* fileSystem.makeDirectory(packageDir, { recursive: true });
298+
yield* fileSystem.writeFileString(`${packageDir}/bin.mjs`, "");
299+
yield* fileSystem.makeDirectory(`${baseDir}/bin`, { recursive: true });
300+
yield* fileSystem.symlink(`${packageDir}/bin.mjs`, `${baseDir}/bin/t3`);
301+
const global = yield* describeWith({}, `${baseDir}/bin/t3`);
302+
expect(global.capabilities.serverInstall).toBe("npm-global");
303+
304+
const checkout = yield* describeWith({}, "/home/theo/Code/t3code/apps/server/src/bin.ts");
305+
expect(checkout.capabilities.serverInstall).toBeUndefined();
306+
307+
// A desktop-managed server updates through the app, so it never hands out a command.
308+
const desktop = yield* describeWith({ mode: "desktop" }, `${baseDir}/bin/t3`);
309+
expect(desktop.capabilities.serverSelfUpdate).toBe("desktop-managed");
310+
expect(desktop.capabilities.serverInstall).toBeUndefined();
311+
}),
312+
);
313+
263314
it.effect("structures persisted environment id filesystem failures", () =>
264315
Effect.gen(function* () {
265316
const fileSystem = yield* FileSystem.FileSystem;

‎apps/server/src/environment/ServerEnvironment.ts‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,11 @@ import {
33
PROVIDER_SEND_TURN_MAX_FILE_BYTES,
44
type ExecutionEnvironmentDescriptor,
55
} from "@t3tools/contracts";
6-
import { HostProcessArchitecture, HostProcessPlatform } from "@t3tools/shared/hostProcess";
6+
import {
7+
HostProcessArchitecture,
8+
HostProcessArguments,
9+
HostProcessPlatform,
10+
} from "@t3tools/shared/hostProcess";
711
import * as Context from "effect/Context";
812
import * as Crypto from "effect/Crypto";
913
import * as Effect from "effect/Effect";
@@ -14,6 +18,7 @@ import * as Schema from "effect/Schema";
1418

1519
import packageJson from "../../package.json" with { type: "json" };
1620
import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
21+
import { detectServerInstall } from "../cli/invocation.ts";
1722
import { readAgentActivityPublishingActive } from "../cloud/config.ts";
1823
import { resolveServerSelfUpdateCapability } from "../cloud/selfUpdate.ts";
1924
import { resolveServiceLauncherMode } from "../cloud/serviceLauncherClient.ts";
@@ -182,11 +187,13 @@ const makeIdentity = Effect.gen(function* () {
182187
/** @public Service construction is part of the canonical Effect module API. */
183188
export const make = Effect.gen(function* () {
184189
const path = yield* Path.Path;
190+
const fileSystem = yield* FileSystem.FileSystem;
185191
const serverConfig = yield* ServerConfig.ServerConfig;
186192
const secrets = yield* ServerSecretStore.ServerSecretStore;
187193
const identity = yield* ServerEnvironmentIdentity;
188194
const hostPlatform = yield* HostProcessPlatform;
189195
const hostArchitecture = yield* HostProcessArchitecture;
196+
const processArguments = yield* HostProcessArguments;
190197
const environmentId = yield* identity.getEnvironmentId;
191198
const cwdBaseName = path.basename(serverConfig.cwd).trim();
192199
const label = yield* resolveServerEnvironmentLabel({ cwdBaseName });
@@ -202,6 +209,16 @@ export const make = Effect.gen(function* () {
202209
// the fd and correctly do not advertise.
203210
const desktopAppUpdate =
204211
serverSelfUpdate === "desktop-managed" && serverConfig.desktopTelemetryControlFd !== undefined;
212+
// Only a server with no self-update path hands the user a command, so only
213+
// that server needs to say which command will land on its install. The bin
214+
// a global install runs is a symlink into the package, so resolve it first.
215+
const entryPath = processArguments[1] ?? "";
216+
const serverInstall =
217+
serverSelfUpdate === null
218+
? detectServerInstall(
219+
yield* fileSystem.realPath(entryPath).pipe(Effect.orElseSucceed(() => entryPath)),
220+
)
221+
: null;
205222

206223
const descriptor: ExecutionEnvironmentDescriptor = {
207224
environmentId,
@@ -235,6 +252,7 @@ export const make = Effect.gen(function* () {
235252
threadPullRequestLinking: true,
236253
environmentIcon: true,
237254
...(serverSelfUpdate === null ? {} : { serverSelfUpdate }),
255+
...(serverInstall === null ? {} : { serverInstall }),
238256
...(serverSelfUpdate === "boot-service" || desktopAppUpdate
239257
? {
240258
serverSelfUpdateProgress: true,

‎apps/web/src/components/ChatView.tsx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -471,6 +471,7 @@ import {
471471
isServerUpdateFailureDismissed,
472472
isVersionMismatchDismissed,
473473
resolveServerConfigVersionMismatch,
474+
resolveServerInstall,
474475
resolveServerSelfUpdateCapability,
475476
serverUpdateGuidance,
476477
supportsDesktopAppUpdate,
@@ -2395,6 +2396,7 @@ export default function ChatView(props: ChatViewProps) {
23952396
const versionMismatchSelfUpdate = resolveServerSelfUpdateCapability(serverConfig);
23962397
const versionMismatchDesktopAppUpdate = supportsDesktopAppUpdate(serverConfig);
23972398
const versionMismatchThreadContinuation = supportsServerUpdateThreadContinuation(serverConfig);
2399+
const versionMismatchInstall = resolveServerInstall(serverConfig);
23982400
const serverUpdateState = useAtomValue(
23992401
serverEnvironment.updateStateAtom(serverUpdateEnvironmentId),
24002402
);
@@ -2535,6 +2537,7 @@ export default function ChatView(props: ChatViewProps) {
25352537
selfUpdate={versionMismatchSelfUpdate}
25362538
desktopAppUpdate={versionMismatchDesktopAppUpdate}
25372539
threadContinuation={versionMismatchThreadContinuation}
2540+
install={versionMismatchInstall}
25382541
targetVersion={versionMismatch.clientVersion}
25392542
label={updateFailed ? "Retry" : "Update"}
25402543
variant="ghost"

‎apps/web/src/components/ServerUpdateAction.tsx‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
import type { EnvironmentId, ServerSelfUpdateCapability } from "@t3tools/contracts";
1+
import type {
2+
EnvironmentId,
3+
ServerInstallKind,
4+
ServerSelfUpdateCapability,
5+
} from "@t3tools/contracts";
26
import type { ServerUpdateStage, ServerUpdateState } from "@t3tools/client-runtime/state/server";
37
import {
48
isAtomCommandInterrupted,
@@ -40,6 +44,9 @@ export interface ServerUpdateTarget {
4044
readonly selfUpdate: ServerSelfUpdateCapability | null;
4145
readonly desktopAppUpdate?: boolean;
4246
readonly threadContinuation?: boolean;
47+
/** How the server is installed (capabilities.serverInstall), which picks
48+
the manual update command when it cannot update itself. */
49+
readonly install?: ServerInstallKind | undefined;
4350
readonly targetVersion: string;
4451
readonly continueThreadsAfterServerUpdate?: boolean;
4552
}
@@ -187,6 +194,7 @@ export function ServerUpdateAction({
187194
selfUpdate,
188195
desktopAppUpdate = false,
189196
threadContinuation = false,
197+
install,
190198
targetVersion,
191199
label = "Update",
192200
variant = "outline",
@@ -252,7 +260,7 @@ export function ServerUpdateAction({
252260
}
253261

254262
if (selfUpdate === null) {
255-
const command = manualServerUpdateCommand(targetVersion);
263+
const command = manualServerUpdateCommand(targetVersion, install);
256264
return (
257265
<Button size={size} variant={variant} onClick={() => copyToClipboard(command, { command })}>
258266
Copy update command

‎apps/web/src/components/chat/useAutoBalanceUpdateBanner.tsx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import {
1212
isServerUpdateFailureDismissed,
1313
isVersionMismatchDismissed,
1414
resolveServerConfigVersionMismatch,
15+
resolveServerInstall,
1516
resolveServerSelfUpdateCapability,
1617
supportsDesktopAppUpdate,
1718
supportsServerUpdateThreadContinuation,
@@ -65,6 +66,7 @@ export function useAutoBalanceUpdateBanner(
6566
selfUpdate,
6667
desktopAppUpdate,
6768
threadContinuation: supportsServerUpdateThreadContinuation(environment.serverConfig),
69+
install: resolveServerInstall(environment.serverConfig),
6870
continueThreadsAfterServerUpdate:
6971
environment.serverConfig?.settings.continueThreadsAfterServerUpdate ?? false,
7072
targetVersion: state.status === "idle" ? mismatch!.clientVersion : state.targetVersion,

‎apps/web/src/components/settings/ConnectionsSettings.tsx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,7 @@ import { isDesktopLocalConnectionTarget } from "~/connection/desktopLocal";
121121
import { useUiStateStore } from "~/uiStateStore";
122122
import {
123123
resolveServerConfigVersionMismatch,
124+
resolveServerInstall,
124125
resolveServerSelfUpdateCapability,
125126
supportsDesktopAppUpdate,
126127
supportsServerUpdateThreadContinuation,
@@ -1552,6 +1553,7 @@ function SavedBackendListRow({
15521553
selfUpdate={resolveServerSelfUpdateCapability(environment.serverConfig)}
15531554
desktopAppUpdate={supportsDesktopAppUpdate(environment.serverConfig)}
15541555
threadContinuation={supportsServerUpdateThreadContinuation(environment.serverConfig)}
1556+
install={resolveServerInstall(environment.serverConfig)}
15551557
targetVersion={versionMismatch.clientVersion}
15561558
label={serverUpdateState.status === "failed" ? "Retry" : "Update"}
15571559
/>
@@ -3177,6 +3179,7 @@ export function ConnectionsSettings() {
31773179
threadContinuation={supportsServerUpdateThreadContinuation(
31783180
primaryServerConfig,
31793181
)}
3182+
install={resolveServerInstall(primaryServerConfig)}
31803183
targetVersion={primaryVersionMismatch.clientVersion}
31813184
label={primaryServerUpdateState.status === "failed" ? "Retry" : "Update"}
31823185
/>

‎apps/web/src/versionSkew.test.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ import {
1414
dismissVersionMismatch,
1515
isServerUpdateFailureDismissed,
1616
isVersionMismatchDismissed,
17+
manualServerUpdateCommand,
1718
resolveServerConfigVersionMismatch,
1819
resolveServerSelfUpdateCapability,
1920
resolveVersionMismatch,
@@ -29,6 +30,17 @@ describe("versionSkew", () => {
2930
branding.APP_VERSION = "0.0.34";
3031
});
3132

33+
it("hands out the update command that matches the server install", () => {
34+
expect(manualServerUpdateCommand("0.0.35", "npm-global")).toBe("npm i -g [email protected]");
35+
expect(manualServerUpdateCommand("0.0.35", "pnpm-global")).toBe("pnpm add -g [email protected]");
36+
expect(manualServerUpdateCommand("0.0.35", "bun-global")).toBe("bun add -g [email protected]");
37+
expect(manualServerUpdateCommand("0.0.35", "npx")).toBe("npx [email protected]");
38+
expect(manualServerUpdateCommand("0.0.35", "pnpm-dlx")).toBe("pnpm dlx [email protected]");
39+
expect(manualServerUpdateCommand("0.0.35", "bunx")).toBe("bunx [email protected]");
40+
// Older servers and dev checkouts report no install; the relaunch stays.
41+
expect(manualServerUpdateCommand("0.0.35", undefined)).toBe("npx [email protected]");
42+
});
43+
3244
it("dismisses only the current failed attempt without clearing its retry state", () => {
3345
const failure = {
3446
status: "failed",

‎apps/web/src/versionSkew.ts‎

Lines changed: 37 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
1-
import type { EnvironmentId, ServerConfig, ServerSelfUpdateCapability } from "@t3tools/contracts";
1+
import type {
2+
EnvironmentId,
3+
ServerConfig,
4+
ServerInstallKind,
5+
ServerSelfUpdateCapability,
6+
} from "@t3tools/contracts";
27
import type { ServerUpdateState } from "@t3tools/client-runtime/state/server";
38
import { compareSemverVersions, parseSemver } from "@t3tools/shared/semver";
49
import * as Schema from "effect/Schema";
@@ -114,9 +119,37 @@ export function supportsServerUpdateThreadContinuation(
114119
return serverConfig?.environment.capabilities.serverUpdateThreadContinuation === true;
115120
}
116121

117-
/** The command to hand users whose server cannot update itself. */
118-
export function manualServerUpdateCommand(targetVersion: string): string {
119-
return `npx t3@${targetVersion}`;
122+
/** How the connected server is installed, when it says. Older servers and
123+
dev checkouts do not. */
124+
export function resolveServerInstall(
125+
serverConfig: Pick<ServerConfig, "environment"> | null | undefined,
126+
): ServerInstallKind | undefined {
127+
return serverConfig?.environment.capabilities.serverInstall;
128+
}
129+
130+
/** The command to hand users whose server cannot update itself. A global
131+
install is upgraded in place; a server started through a package runner
132+
is relaunched at the target version. Servers that do not report their
133+
install keep the npx relaunch. */
134+
export function manualServerUpdateCommand(
135+
targetVersion: string,
136+
install: ServerInstallKind | undefined,
137+
): string {
138+
switch (install) {
139+
case "npm-global":
140+
return `npm i -g t3@${targetVersion}`;
141+
case "pnpm-global":
142+
return `pnpm add -g t3@${targetVersion}`;
143+
case "bun-global":
144+
return `bun add -g t3@${targetVersion}`;
145+
case "pnpm-dlx":
146+
return `pnpm dlx t3@${targetVersion}`;
147+
case "bunx":
148+
return `bunx t3@${targetVersion}`;
149+
case "npx":
150+
case undefined:
151+
return `npx t3@${targetVersion}`;
152+
}
120153
}
121154

122155
export function serverUpdateGuidance(capability: ServerSelfUpdateCapability): string {

0 commit comments

Comments
 (0)