Skip to content

Commit 1c1b8f2

Browse files
t3dotggclaude
andcommitted
feat(web): boot error screen recommends a triage command
When the web bundle fails to start, the screen now shows a command that runs `t3 triage` on this machine. Desktop asks its bridge: `t3 triage` when the CLI is on PATH, else the bundled launcher path, which needs no Node. Everything else, and any failure, falls back to `npx t3 triage`. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent beeb215 commit 1c1b8f2

6 files changed

Lines changed: 136 additions & 5 deletions

File tree

‎apps/desktop/src/app/DesktopCliCommand.test.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,9 +100,15 @@ it.layer(NodeServices.layer)("DesktopCliCommand", (it) => {
100100
const command = yield* commandIn({ home });
101101
const link = path.join(home, ".local", "bin", "t3");
102102

103-
expect(yield* command.state).toEqual({ supported: true, installedPath: null, onPath: false });
103+
expect(yield* command.state).toEqual({
104+
supported: true,
105+
installedPath: null,
106+
onPath: false,
107+
launcherPath: null,
108+
});
104109
const installed = yield* command.install;
105110
expect(installed.installedPath).toBe(link);
111+
expect(installed.launcherPath).toBe(path.join(home, ".t3", "bin", "t3"));
106112
expect(yield* fs.readLink(link)).toBe(path.join(home, ".t3", "bin", "t3"));
107113
expect((yield* command.install).installedPath).toBe(link);
108114

‎apps/desktop/src/app/DesktopCliCommand.ts‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -150,18 +150,26 @@ export const make = Effect.gen(function* () {
150150

151151
const state: DesktopCliCommand["Service"]["state"] = Effect.gen(function* () {
152152
if (!environment.isPackaged) {
153-
return { supported: false, installedPath: null, onPath: false } as const;
153+
return { supported: false, installedPath: null, onPath: false, launcherPath: null } as const;
154154
}
155+
const launcherPath = (yield* exists(launcher)) ? launcher : null;
155156
const installed = yield* installedAt;
156157
const shadowedBy = yield* foreignFirstOnPath;
157158
const shadow = Option.isSome(shadowedBy) ? { shadowedBy: shadowedBy.value } : {};
158159
if (Option.isNone(installed)) {
159-
return { supported: true, installedPath: null, onPath: false, ...shadow };
160+
return { supported: true, installedPath: null, onPath: false, launcherPath, ...shadow };
160161
}
161162
const first = yield* firstOnPath;
162163
const onPath = windows || (Option.isSome(first) && (yield* isOurLink(first.value)));
163-
return { supported: true, installedPath: installed.value, onPath, ...shadow };
164-
}).pipe(Effect.orElseSucceed(() => ({ supported: false, installedPath: null, onPath: false })));
164+
return { supported: true, installedPath: installed.value, onPath, launcherPath, ...shadow };
165+
}).pipe(
166+
Effect.orElseSucceed(() => ({
167+
supported: false,
168+
installedPath: null,
169+
onPath: false,
170+
launcherPath: null,
171+
})),
172+
);
165173

166174
const ensureLauncher = DesktopCliShim.install.pipe(
167175
Effect.provideService(DesktopEnvironment.DesktopEnvironment, environment),

‎apps/web/index.html‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -462,6 +462,19 @@
462462
font: inherit;
463463
cursor: pointer;
464464
}
465+
466+
#boot-error-command {
467+
display: flex;
468+
align-items: center;
469+
gap: 12px;
470+
max-width: 100%;
471+
}
472+
473+
#boot-error code {
474+
font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
475+
overflow-wrap: anywhere;
476+
user-select: all;
477+
}
465478
</style>
466479
<title>T3 Code (Beta)</title>
467480
</head>

‎apps/web/src/lib/bootError.test.ts‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
import type { DesktopBridge, DesktopCliCommandState } from "@t3tools/contracts";
2+
import { describe, expect, it, vi } from "vite-plus/test";
3+
4+
import { resolveTriageCommand } from "./bootError";
5+
6+
const desktopWith = (getState: () => Promise<DesktopCliCommandState>) =>
7+
({ cliCommand: { getState } }) as unknown as DesktopBridge;
8+
9+
const notOnPath = (launcherPath: string | null): DesktopCliCommandState => ({
10+
supported: launcherPath !== null,
11+
installedPath: null,
12+
onPath: false,
13+
launcherPath,
14+
});
15+
16+
describe("resolveTriageCommand", () => {
17+
it("prefers t3 on PATH, then the desktop launcher", async () => {
18+
const onPath = { ...notOnPath("/home/me/.t3/bin/t3"), onPath: true };
19+
await expect(resolveTriageCommand(desktopWith(async () => onPath))).resolves.toBe("t3 triage");
20+
await expect(
21+
resolveTriageCommand(desktopWith(async () => notOnPath("/home/me/.t3/bin/t3"))),
22+
).resolves.toBe("/home/me/.t3/bin/t3 triage");
23+
});
24+
25+
it("quotes launcher paths for the shell that runs them", async () => {
26+
await expect(
27+
resolveTriageCommand(desktopWith(async () => notOnPath("/Users/O'Neil/.t3/bin/t3"))),
28+
).resolves.toBe(`'/Users/O'"'"'Neil/.t3/bin/t3' triage`);
29+
await expect(
30+
resolveTriageCommand(desktopWith(async () => notOnPath("C:\\Users\\Me\\.t3\\bin\\t3.cmd"))),
31+
).resolves.toBe("C:\\Users\\Me\\.t3\\bin\\t3.cmd triage");
32+
await expect(
33+
resolveTriageCommand(
34+
desktopWith(async () => notOnPath("C:\\Users\\Jo O'Neil\\.t3\\bin\\t3.cmd")),
35+
),
36+
).resolves.toBe("& 'C:\\Users\\Jo O''Neil\\.t3\\bin\\t3.cmd' triage");
37+
});
38+
39+
it("falls back to npx without a usable desktop launcher", async () => {
40+
using _warn = vi.spyOn(console, "warn").mockImplementation(() => {});
41+
await expect(resolveTriageCommand(undefined)).resolves.toBe("npx t3 triage");
42+
await expect(resolveTriageCommand({} as DesktopBridge)).resolves.toBe("npx t3 triage");
43+
await expect(resolveTriageCommand(desktopWith(async () => notOnPath(null)))).resolves.toBe(
44+
"npx t3 triage",
45+
);
46+
await expect(
47+
resolveTriageCommand(desktopWith(() => Promise.reject(new Error("ipc closed")))),
48+
).resolves.toBe("npx t3 triage");
49+
});
50+
});

‎apps/web/src/lib/bootError.ts‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,31 @@
1+
import type { DesktopBridge } from "@t3tools/contracts";
2+
3+
const FALLBACK_TRIAGE_COMMAND = "npx t3 triage";
4+
5+
/** The Windows launcher is a `.cmd` run from PowerShell, which needs `&` to run a quoted path. */
6+
function launcherCommand(launcherPath: string) {
7+
if (launcherPath.endsWith(".cmd")) {
8+
return /^[\w:\\.-]+$/.test(launcherPath)
9+
? launcherPath
10+
: `& '${launcherPath.replace(/['\u2018\u2019\u201A\u201B]/g, "$&$&")}'`;
11+
}
12+
return /^[\w@%+=:,./-]+$/.test(launcherPath)
13+
? launcherPath
14+
: `'${launcherPath.replaceAll("'", `'"'"'`)}'`;
15+
}
16+
17+
/** Desktop can run its bundled launcher without Node; everything else falls back to npx. */
18+
export async function resolveTriageCommand(bridge: DesktopBridge | undefined) {
19+
try {
20+
const state = await bridge?.cliCommand?.getState();
21+
if (state?.onPath) return "t3 triage";
22+
if (state?.launcherPath) return `${launcherCommand(state.launcherPath)} triage`;
23+
} catch (error) {
24+
console.warn("Could not read the desktop CLI state.", error);
25+
}
26+
return FALLBACK_TRIAGE_COMMAND;
27+
}
28+
129
export function showBootError(error: unknown) {
230
console.error("T3 Code failed to start.", error);
331
const bootShell = document.getElementById("boot-shell");
@@ -22,5 +50,29 @@ export function showBootError(error: unknown) {
2250
reload.textContent = "Reload";
2351
reload.addEventListener("click", () => window.location.reload());
2452
content.append(reload);
53+
54+
const hint = document.createElement("p");
55+
hint.textContent = "If Reload does not fix the problem, run this command in a terminal:";
56+
const command = document.createElement("code");
57+
command.textContent = FALLBACK_TRIAGE_COMMAND;
58+
const commandRow = document.createElement("div");
59+
commandRow.id = "boot-error-command";
60+
commandRow.append(command);
61+
// The clipboard API exists only in secure contexts, such as HTTPS and the desktop app.
62+
if (window.isSecureContext) {
63+
const copy = document.createElement("button");
64+
copy.type = "button";
65+
copy.textContent = "Copy";
66+
copy.addEventListener("click", () => {
67+
navigator.clipboard.writeText(command.textContent ?? "").then(
68+
() => (copy.textContent = "Copied"),
69+
(copyError) => console.warn("Could not copy the triage command.", copyError),
70+
);
71+
});
72+
commandRow.append(copy);
73+
}
74+
content.append(hint, commandRow);
2575
bootShell.replaceChildren(content);
76+
77+
void resolveTriageCommand(window.desktopBridge).then((value) => (command.textContent = value));
2678
}

‎packages/contracts/src/ipc.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -321,6 +321,8 @@ export const DesktopCliCommandStateSchema = Schema.Struct({
321321
installedPath: Schema.NullOr(Schema.String),
322322
onPath: Schema.Boolean,
323323
shadowedBy: Schema.optionalKey(Schema.String),
324+
/** The app's bundled `t3` launcher, which runs without Node or a PATH entry. */
325+
launcherPath: Schema.NullOr(Schema.String),
324326
});
325327
export type DesktopCliCommandState = typeof DesktopCliCommandStateSchema.Type;
326328

0 commit comments

Comments
 (0)