sailfork / t3code-github / apps/ web/ src/ lib/ bootError.ts

import type { DesktopBridge, DesktopUpdateState } from "@t3tools/contracts";

const FALLBACK_TRIAGE_COMMAND = "npx t3 triage";
const DOWNLOAD_URL = "https://t3.codes/download";
const ISSUE_URL = "https://github.com/pingdotgg/t3code/issues/new";
const LAST_FAILURE_KEY = "t3code:boot-failed-at";
const REPEAT_FAILURE_MS = 5 * 60_000;
const MAX_CAUSES = 3;
const MAX_ERROR_CHARS = 6_000;
const COPY_BLOCKED = "Copy was blocked. The text is selected so you can copy it manually.";
const UPDATE_DOWNLOAD_FAILED = "The update download failed. Try Download update again.";
const UPDATE_INSTALL_FAILED = "The update install failed. Try Restart to update again.";

/** The Windows launcher is a `.cmd` run from PowerShell, which needs `&` to run a quoted path. */
function launcherCommand(launcherPath: string) {
  if (launcherPath.endsWith(".cmd")) {
    return /^[\w:\\.-]+$/.test(launcherPath)
      ? launcherPath
      : `& '${launcherPath.replace(/['\u2018\u2019\u201A\u201B]/g, "

Loading Sailfork

amp;

Loading Sailfork

amp;")}'`; } return /^[\w@%+=:,./-]+$/.test(launcherPath) ? launcherPath : `'${launcherPath.replaceAll("'", `'"'"'`)}'`; } /** Desktop can run its bundled launcher without Node; everything else falls back to npx. */ export async function resolveTriageCommand(bridge: DesktopBridge | undefined) { try { const state = await bridge?.cliCommand.getState(); // Windows reports onPath from its PATH entry alone; only an existing launcher proves it runs. if (state?.launcherPath) { return state.onPath ? "t3 triage" : `${launcherCommand(state.launcherPath)} triage`; } } catch (error) { console.warn("Could not read the desktop CLI state.", error); } return FALLBACK_TRIAGE_COMMAND; } /** The update button only appears when the desktop updater has a newer build to offer. */ export function updateActionFor(state: DesktopUpdateState | null | undefined) { switch (state?.status) { case "available": return { kind: "download" } as const; case "downloading": return { kind: "downloading", percent: Math.round(state.downloadPercent ?? 0) } as const; case "downloaded": return { kind: "install" } as const; default: return null; } } function safeString(value: unknown) { try { return String(value); } catch { return ""; } } function describeOne(value: unknown) { if (value instanceof Error) { const header = value.message ? `${value.name}: ${value.message}` : value.name; // V8 stacks start with the header; Safari and Firefox stacks do not. const stack = typeof value.stack === "string" ? value.stack : ""; return stack === header || stack.startsWith(`${header}\n`) ? stack : [header, stack].filter(Boolean).join("\n"); } if (typeof value === "string") return value; try { return JSON.stringify(value) ?? safeString(value); } catch { return safeString(value); } } /** Hosts can name private machines, and pairing tokens live in query strings and hashes. */ function redact(text: string) { return text .replace(/\b[a-z][\w+.-]*:\/\/[^\s/?#'"()]+/gi, "") .replace(/[?#][^\s'"()]*=[^\s'"()]*?((?::\d+){1,2})?(?=[\s'"()]|$)/g, "$1"); } export interface BootErrorEnvironment { readonly version: string; readonly channel: string; readonly surface: "desktop" | "web"; readonly platform: string; readonly userAgent: string; readonly time: string; } /** Plain text that is shown and copied as-is, so users see exactly what they share. */ export function buildErrorReport(error: unknown, environment: BootErrorEnvironment) { const parts: Array<string> = []; const seen = new Set<unknown>(); let current = error; while (current != null && !seen.has(current) && parts.length <= MAX_CAUSES) { seen.add(current); const text = describeOne(current); parts.push(parts.length === 0 ? text : `Caused by: ${text}`); current = current instanceof Error ? current.cause : undefined; } let details = redact(parts.join("\n") || "(no error message)"); if (details.length > MAX_ERROR_CHARS) { details = `${details.slice(0, MAX_ERROR_CHARS)}\n[truncated]`; } return [ details, "", `Version: ${environment.version}`, `Channel: ${environment.channel}`, `Surface: ${environment.surface}`, `Platform: ${environment.platform}`, `User agent: ${environment.userAgent}`, `Time: ${environment.time}`, ].join("\n"); } function clientPlatform(bridge: DesktopBridge | undefined) { try { return bridge?.getClientPlatform() ?? navigator.platform; } catch { return navigator.platform; } } function readEnvironment(bridge: DesktopBridge | undefined): BootErrorEnvironment { const version = import.meta.env.APP_VERSION; return { version, channel: import.meta.env.VITE_RELEASE_CHANNEL || /-(nightly|preview)\./.exec(version)?.[1] || "stable", surface: bridge ? "desktop" : "web", platform: clientPlatform(bridge), userAgent: navigator.userAgent, time: new Date().toISOString(), }; } /** Opens More options by default when startup already failed in this tab a moment ago. */ function isRepeatFailure(now: number) { try { const previous = Number(sessionStorage.getItem(LAST_FAILURE_KEY)); sessionStorage.setItem(LAST_FAILURE_KEY, String(now)); return now - previous < REPEAT_FAILURE_MS; } catch { return false; } } const icon = (paths: string) => `<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${paths}</svg>`; const COPY_ICON = icon( '<rect width="14" height="14" x="8" y="8" rx="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/>', ); const CHECK_ICON = icon('<path d="M20 6 9 17l-5-5"/>'); function element<K extends keyof HTMLElementTagNameMap>( tag: K, props: Partial<HTMLElementTagNameMap[K]> = {}, children: ReadonlyArray<Node | string> = [], ) { const node = Object.assign(document.createElement(tag), props); node.append(...children); return node; } function selectContents(target: HTMLElement) { const range = document.createRange(); range.selectNodeContents(target); const selection = window.getSelection(); selection?.removeAllRanges(); selection?.addRange(range); } function copySelection() { try { return document.execCommand("copy"); } catch { return false; } } /** Plain http has no Clipboard API, but the legacy copy command still works on a selection. */ function copyText(target: HTMLElement, onCopied: () => void, onBlocked: (hint: string) => void) { const fallback = () => { selectContents(target); if (copySelection()) return onCopied(); onBlocked( /Mac|iPhone|iPad/.test(navigator.platform) ? "Press ⌘C to copy" : "Press Ctrl+C to copy", ); }; const clipboard = window.isSecureContext ? navigator.clipboard : undefined; if (typeof clipboard?.writeText !== "function") return fallback(); clipboard.writeText(target.textContent ?? "").then(onCopied, fallback); } function mountUpdateButton( bridge: DesktopBridge, button: HTMLButtonElement, note: HTMLParagraphElement, announce: (text: string) => void, ) { let action: ReturnType<typeof updateActionFor> = null; const render = (state: DesktopUpdateState) => { action = updateActionFor(state); button.hidden = action === null; // aria-disabled keeps keyboard focus on the button while the download runs. button.setAttribute("aria-disabled", String(action?.kind === "downloading")); if (action?.kind === "download") button.textContent = "Download update"; if (action?.kind === "downloading") button.textContent = `Downloading update (${action.percent}%)`; if (action?.kind === "install") button.textContent = "Restart to update"; const failure = !action ? "" : state.errorContext === "download" ? UPDATE_DOWNLOAD_FAILED : state.errorContext === "install" ? UPDATE_INSTALL_FAILED : ""; if (failure === note.textContent) return; note.textContent = failure; note.hidden = !failure; if (failure) announce(failure); }; button.addEventListener("click", () => { const run = action?.kind === "install" ? bridge.installUpdate() : action?.kind === "download" ? bridge.downloadUpdate() : undefined; run?.then( (result) => render(result.state), (error: unknown) => console.warn("Could not update T3 Code.", error), ); }); // A pushed state is newer than the initial read, so the read must not overwrite it. let pushed = false; try { bridge.onUpdateState((state) => { pushed = true; render(state); }); bridge.getUpdateState().then( (state) => pushed || render(state), (error: unknown) => console.warn("Could not read the desktop update state.", error), ); } catch (error) { console.warn("Could not read the desktop update state.", error); } } export function showBootError(error: unknown) { console.error("T3 Code failed to start.", error); const bootShell = document.getElementById("boot-shell"); if (!bootShell) return; const bridge = window.desktopBridge; const environment = readEnvironment(bridge); const offline = !bridge && navigator.onLine === false; const status = element("span", { className: "boot-error-sr" }); status.setAttribute("aria-live", "polite"); // Clearing first makes screen readers announce a repeated message. let announcement: ReturnType<typeof setTimeout> | undefined; const announce = (text: string) => { clearTimeout(announcement); status.textContent = ""; announcement = setTimeout(() => (status.textContent = text), 100); }; const message = element("div", {}, [ element("h1", { textContent: "T3 Code failed to start" }), element("p", { textContent: offline ? "This browser appears to be offline. Check the connection, then reload." : "We are not sure why. Try a reload first.", }), ]); message.setAttribute("role", "alert"); const reload = element("button", { id: "boot-error-reload", type: "button", textContent: "Reload", }); reload.addEventListener("click", () => window.location.reload()); const update = element("button", { id: "boot-error-update", type: "button", hidden: true }); const updateNote = element("p", { id: "boot-error-update-note", hidden: true }); if (bridge) mountUpdateButton(bridge, update, updateNote, announce); const command = element("code", { textContent: FALLBACK_TRIAGE_COMMAND }); const copyCommand = element("button", { className: "boot-error-icon", type: "button", title: "Copy command", innerHTML: COPY_ICON, }); copyCommand.setAttribute("aria-label", "Copy command"); copyCommand.addEventListener("click", () => copyText( command, () => { copyCommand.innerHTML = CHECK_ICON; copyCommand.title = "Copied"; copyCommand.setAttribute("aria-label", "Copied"); announce("Copied to clipboard."); }, (hint) => { copyCommand.textContent = hint; copyCommand.title = hint; copyCommand.setAttribute("aria-label", hint); announce(COPY_BLOCKED); }, ), ); void resolveTriageCommand(bridge).then((value) => (command.textContent = value)); let report = "(no error message)"; try { report = buildErrorReport(error, environment); } catch (reportError) { console.warn("Could not describe the startup error.", reportError); } const details = element("pre", { id: "boot-error-details", tabIndex: 0, textContent: report }); const copyDetails = element("button", { type: "button", textContent: "Copy error details" }); copyDetails.addEventListener("click", () => copyText( details, () => { copyDetails.textContent = "Copied"; announce("Copied to clipboard."); }, (hint) => { copyDetails.textContent = hint; announce(COPY_BLOCKED); }, ), ); const issue = new URL(ISSUE_URL); issue.searchParams.set("template", "bug_report.yml"); issue.searchParams.set("title", "T3 Code failed to start"); issue.searchParams.set("area", "apps/web"); issue.searchParams.set("version", `${environment.version} (${environment.channel})`); issue.searchParams.set("environment", `${environment.surface}, ${environment.platform}`); const link = (href: string, textContent: string) => element("a", { href, textContent, target: "_blank", rel: "noreferrer" }); const nightly = environment.channel === "nightly"; const more = element("details", { open: isRepeatFailure(Date.now()) }, [ element("summary", { textContent: "More options if it keeps failing" }), ...(bridge ? [ link( nightly ? `${DOWNLOAD_URL}?channel=nightly` : DOWNLOAD_URL, nightly ? "Download and reinstall the latest nightly build" : "Download and reinstall T3 Code", ), ] : []), element("div", {}, [ element("p", { textContent: "Run this on the computer that runs T3 Code. Your agent can check the local logs and help you file a bug report.", }), element("div", { id: "boot-error-command" }, [command, copyCommand]), ]), element("div", {}, [ details, element("p", { textContent: "Details may include local file paths and names. Check before sharing.", }), element("div", { id: "boot-error-report" }, [ copyDetails, link(issue.href, "File a bug report on GitHub"), ]), ]), ]); bootShell.replaceChildren( element("div", { id: "boot-error" }, [ message, element("div", { id: "boot-error-actions" }, [reload, update]), updateNote, more, status, ]), ); }