feat(pairing): QR offer + app scanner

packages/server/src/server/bootstrap.ts

@@ -53,6 +53,7 @@ import {
   createConnectionOfferV1,
   encodeOfferToFragmentUrl,
 } from "./connection-offer.js";
+import { printPairingQrIfEnabled } from "./pairing-qr.js";
 import { startRelayTransport, type RelayTransportController } from "./relay-transport.js";
 import type {
   AgentClient,
@@ -420,6 +421,7 @@ export async function createPaseoDaemon(
 
             const url = encodeOfferToFragmentUrl({ offer, appBaseUrl });
             logger.info({ url }, "pairing_offer");
+            void printPairingQrIfEnabled({ url, logger }).catch(() => undefined);
 
             if (relayEnabled) {
               relayTransport?.stop().catch(() => undefined);

packages/server/src/server/pairing-qr.ts

@@ -0,0 +1,50 @@
+import * as QRCode from "qrcode";
+import type { QRCodeToStringOptionsTerminal, QRCodeToStringOptionsOther } from "qrcode";
+import type { Logger } from "pino";
+
+function parseBooleanEnv(value: string | undefined): boolean | undefined {
+  if (value === undefined) return undefined;
+  const normalized = value.trim().toLowerCase();
+  if (["1", "true", "yes", "y", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "n", "off"].includes(normalized)) return false;
+  return undefined;
+}
+
+function shouldPrintPairingQr(): boolean {
+  const env = parseBooleanEnv(process.env.PASEO_PAIRING_QR);
+  if (env !== undefined) return env;
+  return Boolean(process.stdout.isTTY);
+}
+
+async function renderQr(url: string): Promise<string> {
+  const terminalOptions: QRCodeToStringOptionsTerminal = {
+    type: "terminal",
+    small: true,
+  };
+
+  const utf8Options: QRCodeToStringOptionsOther = {
+    type: "utf8",
+  };
+
+  try {
+    return await QRCode.toString(url, terminalOptions);
+  } catch {
+    return await QRCode.toString(url, utf8Options);
+  }
+}
+
+export async function printPairingQrIfEnabled(args: {
+  url: string;
+  logger?: Logger;
+}): Promise<void> {
+  if (!shouldPrintPairingQr()) return;
+
+  const qr = await renderQr(args.url);
+  const out = `\nScan to pair:\n${qr}\n${args.url}\n`;
+
+  try {
+    process.stdout.write(out);
+  } catch (error) {
+    args.logger?.debug({ error }, "Failed to print pairing QR");
+  }
+}