Skip to content

Commit 43456e2

Browse files
committed
feat(desktop): add remote environments from t3code://pair deep links
Clicking a pairing link in a browser or chat had no way to reach the desktop app; users had to copy the URL and paste it into Settings. The desktop app already owns the t3code:// scheme OS-wide but consumed no incoming URLs. A new DesktopPairingLink service listens for open-url (macOS), second-instance argv (Windows/Linux), and cold-start argv, filters for <scheme>://pair, and forwards the link to the renderer. A link that arrives before the renderer is ready is held and delivered once the coordinator signals readiness. The renderer parses host, label, and token with the existing hosted-pairing reader, asks the user to confirm the host, then registers the environment through connectPairing and switches to it. The link is the hosted pairing format on the desktop scheme: t3code://pair?host=<backend>&label=<name>#token=<credential>
1 parent 0150c6a commit 43456e2

17 files changed

Lines changed: 359 additions & 0 deletions

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ import * as DesktopBackendPool from "../backend/DesktopBackendPool.ts";
2121
import * as DesktopEnvironment from "./DesktopEnvironment.ts";
2222
import * as DesktopLifecycle from "./DesktopLifecycle.ts";
2323
import * as DesktopLinuxUrlHandler from "./DesktopLinuxUrlHandler.ts";
24+
import * as DesktopPairingLink from "./DesktopPairingLink.ts";
2425
import * as DesktopObservability from "./DesktopObservability.ts";
2526
import * as DesktopPreReadyPlatform from "./DesktopPreReadyPlatform.ts";
2627
import * as DesktopShutdown from "./DesktopShutdown.ts";
@@ -263,6 +264,7 @@ const startup = Effect.gen(function* () {
263264
const electronApp = yield* ElectronApp.ElectronApp;
264265
const lifecycle = yield* DesktopLifecycle.DesktopLifecycle;
265266
const linuxUrlHandler = yield* DesktopLinuxUrlHandler.DesktopLinuxUrlHandler;
267+
const pairingLink = yield* DesktopPairingLink.DesktopPairingLink;
266268
const clerk = yield* DesktopClerk.DesktopClerk;
267269
const shellEnvironment = yield* DesktopShellEnvironment.DesktopShellEnvironment;
268270
const desktopSettings = yield* DesktopAppSettings.DesktopAppSettings;
@@ -310,6 +312,7 @@ const startup = Effect.gen(function* () {
310312
yield* appIdentity.configure;
311313
yield* lifecycle.register;
312314
yield* clerk.configure;
315+
yield* pairingLink.register;
313316

314317
yield* electronApp.whenReady.pipe(
315318
Effect.withSpan("desktop.electron.whenReady"),

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,7 @@ function makeDesktopWindowLayer(
9696
prepareCaptureReveal: Effect.void,
9797
dispatchMenuAction: () => Effect.void,
9898
dispatchSnapShotEvent: () => Effect.void,
99+
dispatchPairingLink: () => Effect.void,
99100
zoomMain: () => Effect.void,
100101
syncAppearance: Effect.void,
101102
});
Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
import { describe, expect, it } from "vite-plus/test";
2+
3+
import { extractPairingLink } from "./DesktopPairingLink.ts";
4+
5+
const link = "t3code://pair?host=https%3A%2F%2Fbackend.example.com&label=Work#token=ABCD1234";
6+
7+
describe("extractPairingLink", () => {
8+
it("finds the pairing link among launcher argv noise", () => {
9+
expect(
10+
extractPairingLink(["/usr/bin/t3code", "--no-sandbox", link, "--foo=bar"], "t3code"),
11+
).toBe(link);
12+
});
13+
14+
it("returns null when no candidate is a pairing link", () => {
15+
expect(extractPairingLink(["/usr/bin/t3code", "--no-sandbox"], "t3code")).toBeNull();
16+
expect(extractPairingLink([], "t3code")).toBeNull();
17+
});
18+
19+
it("ignores links on another scheme", () => {
20+
expect(extractPairingLink([link], "t3code-dev")).toBeNull();
21+
expect(
22+
extractPairingLink(["https://backend.example.com/pair#token=ABCD1234"], "t3code"),
23+
).toBeNull();
24+
});
25+
26+
it("ignores the renderer origin and unknown hosts on the same scheme", () => {
27+
expect(extractPairingLink(["t3code://app/"], "t3code")).toBeNull();
28+
expect(extractPairingLink(["t3code://app/settings?host=x#token=y"], "t3code")).toBeNull();
29+
expect(extractPairingLink(["t3code://other?host=x#token=y"], "t3code")).toBeNull();
30+
});
31+
32+
it("matches the scheme case-insensitively and keeps the token fragment", () => {
33+
const result = extractPairingLink(["T3CODE://pair?host=h#token=t"], "t3code");
34+
expect(result).not.toBeNull();
35+
const url = new URL(result!);
36+
expect(url.host).toBe("pair");
37+
expect(url.searchParams.get("host")).toBe("h");
38+
expect(url.hash).toBe("#token=t");
39+
});
40+
41+
it("skips malformed candidates without throwing", () => {
42+
expect(extractPairingLink(["t3code:", "t3code://", link], "t3code")).toBe(link);
43+
});
44+
});
Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
import * as Context from "effect/Context";
2+
import * as Effect from "effect/Effect";
3+
import * as Layer from "effect/Layer";
4+
import * as Option from "effect/Option";
5+
import * as Ref from "effect/Ref";
6+
import * as Scope from "effect/Scope";
7+
8+
import type * as Electron from "electron";
9+
10+
import * as ElectronApp from "../electron/ElectronApp.ts";
11+
import * as ElectronProtocol from "../electron/ElectronProtocol.ts";
12+
import * as DesktopWindow from "../window/DesktopWindow.ts";
13+
import * as DesktopEnvironment from "./DesktopEnvironment.ts";
14+
import { makeComponentLogger } from "./DesktopObservability.ts";
15+
16+
/** Host segment of a pairing deep link: `t3code://pair?host=...&label=...#token=...`. */
17+
export const PAIRING_LINK_HOST = "pair";
18+
19+
/**
20+
* Pick the pairing deep link out of a list of candidate strings (an argv, or a
21+
* single URL from macOS `open-url`). Only links on this build's own scheme with
22+
* the `pair` host count; the renderer parses host/label/token from it.
23+
*/
24+
export function extractPairingLink(
25+
candidates: ReadonlyArray<string>,
26+
scheme: string,
27+
): string | null {
28+
const prefix = `${scheme}:`;
29+
for (const candidate of candidates) {
30+
const trimmed = candidate.trim();
31+
if (!trimmed.toLowerCase().startsWith(prefix)) continue;
32+
let url: URL;
33+
try {
34+
url = new URL(trimmed);
35+
} catch {
36+
continue;
37+
}
38+
if (url.protocol.toLowerCase() !== prefix || url.host !== PAIRING_LINK_HOST) continue;
39+
return url.toString();
40+
}
41+
return null;
42+
}
43+
44+
export class DesktopPairingLink extends Context.Service<
45+
DesktopPairingLink,
46+
{
47+
/**
48+
* Start listening for pairing deep links. Registers before `ready` so a
49+
* macOS `open-url` delivered at cold start is not missed.
50+
*/
51+
readonly register: Effect.Effect<void, never, Scope.Scope>;
52+
/**
53+
* The renderer signals when its coordinator is mounted; a link that
54+
* arrived earlier (cold start) is delivered then.
55+
*/
56+
readonly setRendererReady: (ready: boolean) => Effect.Effect<void>;
57+
}
58+
>()("@t3tools/desktop/app/DesktopPairingLink") {}
59+
60+
const { logInfo, logWarning } = makeComponentLogger("desktop-pairing-link");
61+
62+
/** @public Service construction is part of the canonical Effect module API. */
63+
export const make = Effect.gen(function* () {
64+
const environment = yield* DesktopEnvironment.DesktopEnvironment;
65+
const electronApp = yield* ElectronApp.ElectronApp;
66+
const desktopWindow = yield* DesktopWindow.DesktopWindow;
67+
const runPromise = Effect.runPromiseWith(yield* Effect.context<never>());
68+
const scheme = ElectronProtocol.getDesktopScheme(environment.isDevelopment);
69+
70+
const pendingRef = yield* Ref.make(Option.none<string>());
71+
const rendererReadyRef = yield* Ref.make(false);
72+
73+
const deliver = Effect.fn("desktop.pairingLink.deliver")(function* (link: string) {
74+
yield* logInfo("delivering pairing link to renderer");
75+
yield* desktopWindow.dispatchPairingLink(link);
76+
});
77+
78+
// Reveal the window right away so the click feels acknowledged, but hold
79+
// the link until the renderer says it can act on it.
80+
const receive = Effect.fn("desktop.pairingLink.receive")(function* (link: string) {
81+
yield* Ref.set(pendingRef, Option.some(link));
82+
if (yield* Ref.get(rendererReadyRef)) {
83+
yield* Ref.set(pendingRef, Option.none());
84+
yield* deliver(link);
85+
return;
86+
}
87+
yield* logInfo("holding pairing link until renderer is ready");
88+
yield* desktopWindow.activate;
89+
});
90+
91+
const receiveFromCandidates = (candidates: ReadonlyArray<string>) => {
92+
const link = extractPairingLink(candidates, scheme);
93+
if (link === null) return;
94+
void runPromise(
95+
receive(link).pipe(
96+
Effect.catchCause((cause) => logWarning("failed to handle pairing link", { cause })),
97+
),
98+
);
99+
};
100+
101+
const register = Effect.gen(function* () {
102+
// macOS hands URLs to the running (or launching) app via open-url. The
103+
// Clerk bridge also listens here but only claims its own renderer origin.
104+
yield* electronApp.on<[Electron.Event, string]>("open-url", (_event, url) => {
105+
receiveFromCandidates([url]);
106+
});
107+
// Windows and Linux launch a second process with the URL in argv; the
108+
// primary instance receives that argv here.
109+
yield* electronApp.on<[Electron.Event, ReadonlyArray<string>, string]>(
110+
"second-instance",
111+
(_event, argv) => {
112+
receiveFromCandidates(argv);
113+
},
114+
);
115+
// Cold start on Windows/Linux: the URL is in this process's own argv.
116+
receiveFromCandidates(process.argv);
117+
}).pipe(Effect.withSpan("desktop.pairingLink.register"));
118+
119+
const setRendererReady = Effect.fn("desktop.pairingLink.setRendererReady")(function* (
120+
ready: boolean,
121+
) {
122+
yield* Ref.set(rendererReadyRef, ready);
123+
if (!ready) return;
124+
const pending = yield* Ref.getAndSet(pendingRef, Option.none());
125+
if (Option.isSome(pending)) {
126+
yield* deliver(pending.value).pipe(
127+
Effect.catchCause((cause) => logWarning("failed to deliver pairing link", { cause })),
128+
);
129+
}
130+
});
131+
132+
return DesktopPairingLink.of({ register, setRendererReady });
133+
});
134+
135+
export const layer = Layer.effect(DesktopPairingLink, make);

‎apps/desktop/src/backend/DesktopBackendPool.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,7 @@ function makePoolLayer(
9999
prepareCaptureReveal: Effect.void,
100100
dispatchMenuAction: () => Effect.die("unexpected menu action"),
101101
dispatchSnapShotEvent: () => Effect.void,
102+
dispatchPairingLink: () => Effect.die("unexpected pairing link"),
102103
zoomMain: () => Effect.die("unexpected zoom"),
103104
syncAppearance: Effect.void,
104105
} satisfies DesktopWindow.DesktopWindow["Service"]),

‎apps/desktop/src/ipc/DesktopIpcHandlers.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@ import {
6969
} from "./methods/snapShot.ts";
7070
import * as PreviewIpc from "./methods/preview.ts";
7171
import * as AppActivationIpc from "./methods/appActivation.ts";
72+
import * as PairingLinkIpc from "./methods/pairingLink.ts";
7273
import { getWslState, setWslBackendEnabled, setWslDistro, setWslOnly } from "./methods/wsl.ts";
7374

7475
export const installDesktopIpcHandlers = Effect.fn("desktop.ipc.installHandlers")(function* () {
@@ -78,6 +79,7 @@ export const installDesktopIpcHandlers = Effect.fn("desktop.ipc.installHandlers"
7879

7980
yield* ipc.handle(AppActivationIpc.setReady);
8081
yield* ipc.handle(AppActivationIpc.complete);
82+
yield* ipc.handle(PairingLinkIpc.setReady);
8183

8284
yield* ipc.handleSync(getAppBranding);
8385
yield* ipc.handleSync(getSystemLocale);

‎apps/desktop/src/ipc/channels.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ export const WINDOW_FULLSCREEN_STATE_CHANNEL = "desktop:window-fullscreen-state"
1616
export const DESKTOP_APP_ACTIVATION_READY_CHANNEL = "desktop:app-activation-ready";
1717
export const DESKTOP_APP_ACTIVATION_COMPLETE_CHANNEL = "desktop:app-activation-complete";
1818
export const DESKTOP_APP_ACTIVATION_REQUEST_CHANNEL = "desktop:app-activation-request";
19+
export const PAIRING_LINK_READY_CHANNEL = "desktop:pairing-link-ready";
20+
export const PAIRING_LINK_CHANNEL = "desktop:pairing-link";
1921
export const UPDATE_STATE_CHANNEL = "desktop:update-state";
2022
export const UPDATE_GET_STATE_CHANNEL = "desktop:update-get-state";
2123
export const UPDATE_SET_CHANNEL_CHANNEL = "desktop:update-set-channel";
Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import * as Effect from "effect/Effect";
2+
import * as Schema from "effect/Schema";
3+
4+
import * as DesktopPairingLink from "../../app/DesktopPairingLink.ts";
5+
import * as IpcChannels from "../channels.ts";
6+
import * as DesktopIpc from "../DesktopIpc.ts";
7+
8+
export const setReady = DesktopIpc.makeIpcMethod({
9+
channel: IpcChannels.PAIRING_LINK_READY_CHANNEL,
10+
payload: Schema.Boolean,
11+
result: Schema.Void,
12+
handler: Effect.fn("desktop.ipc.pairingLink.setReady")(function* (ready) {
13+
const pairingLink = yield* DesktopPairingLink.DesktopPairingLink;
14+
yield* pairingLink.setRendererReady(ready);
15+
}),
16+
});

‎apps/desktop/src/main.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ import * as DesktopNetworkInterfaces from "./backend/DesktopNetworkInterfaces.ts
4545
import * as DesktopEnvironment from "./app/DesktopEnvironment.ts";
4646
import * as DesktopLifecycle from "./app/DesktopLifecycle.ts";
4747
import * as DesktopLinuxUrlHandler from "./app/DesktopLinuxUrlHandler.ts";
48+
import * as DesktopPairingLink from "./app/DesktopPairingLink.ts";
4849
import * as DesktopShutdown from "./app/DesktopShutdown.ts";
4950
import * as DesktopObservability from "./app/DesktopObservability.ts";
5051
import * as DesktopServerExposure from "./backend/DesktopServerExposure.ts";
@@ -164,6 +165,7 @@ const desktopSnapShotLayer = DesktopSnapShot.layer.pipe(
164165
const desktopAppActivationLayer = DesktopAppActivation.layer.pipe(
165166
Layer.provide(desktopWindowLayer),
166167
);
168+
const desktopPairingLinkLayer = DesktopPairingLink.layer.pipe(Layer.provide(desktopWindowLayer));
167169

168170
// Pool layer instantiates the backend factory once for the Windows
169171
// primary instance and exposes it via pool.primary. Consumers go through
@@ -193,6 +195,7 @@ const desktopLocalEnvironmentAuthLayer = DesktopLocalEnvironmentAuth.layer.pipe(
193195
const desktopApplicationLayer = Layer.mergeAll(
194196
DesktopLifecycle.layer,
195197
desktopAppActivationLayer,
198+
desktopPairingLinkLayer,
196199
DesktopApplicationMenu.layer,
197200
DesktopLinuxUrlHandler.layer,
198201
DesktopShellEnvironment.layer,

‎apps/desktop/src/preload.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -275,6 +275,19 @@ contextBridge.exposeInMainWorld("desktopBridge", {
275275
};
276276
},
277277
},
278+
pairingLink: {
279+
setReady: (ready) => ipcRenderer.invoke(IpcChannels.PAIRING_LINK_READY_CHANNEL, ready),
280+
onLink: (listener) => {
281+
const wrappedListener = (_event: Electron.IpcRendererEvent, url: unknown) => {
282+
if (typeof url !== "string") return;
283+
listener(url);
284+
};
285+
ipcRenderer.on(IpcChannels.PAIRING_LINK_CHANNEL, wrappedListener);
286+
return () => {
287+
ipcRenderer.removeListener(IpcChannels.PAIRING_LINK_CHANNEL, wrappedListener);
288+
};
289+
},
290+
},
278291
preview: {
279292
createTab: (tabId, defaults) =>
280293
ipcRenderer.invoke(IpcChannels.PREVIEW_CREATE_TAB_CHANNEL, {

0 commit comments

Comments
 (0)