fix(dev): warn when a browser cannot be opened and caption qr codes

Author: danielroe

packages/nuxt-cli/src/dev/listen.ts

@@ -250,14 +250,15 @@ async function resolvePort(requestedPort: number | undefined, hostname: string,
 returnport
 }
 
-exportasyncfunctionprintQRCode(url: string): Promise<void>{
+exportasyncfunctionprintQRCode(url: string,{ showURL =false}: {showURL?: boolean}={}): Promise<void>{
 const{ renderUnicodeCompact }=awaitimport('uqr')
+constcaption=showURL ? `\n${centerBlock(colors.cyan(url),url.length)}` : ''
 // eslint-disable-next-line no-console
-console.log(`\n${centerBlock(renderUnicodeCompact(url))}\n`)
+console.log(`\n${centerBlock(renderUnicodeCompact(url))}${caption}\n`)
 }
 
 exportasyncfunctioncopyURL(url: string): Promise<void>{
-if(!isClipboardAvailable()){
+if(!hasDisplayServer()){
 logger.warn('No clipboard is available in this environment.')
 return
 }
@@ -275,20 +276,21 @@ export async function copyURL(url: string): Promise<void> {
 constDISPLAY_REQUIRED_PLATFORMS=newSet<NodeJS.Platform>(['linux','freebsd','openbsd'])
 
 /**
- * Clipboard tools on Linux and BSD (`wl-copy`, `xsel`, `xclip`) need a display
- * server. Without one they exit before receiving any input, and the resulting
- * `EPIPE` escapes as an uncaught exception from inside the writing library.
+ * Whether a graphical session exists to receive a clipboard write or a browser
+ * launch. The tools involved on Linux and BSD (`wl-copy`, `xsel`, `xclip`,
+ * `xdg-open`) all need one, and fail in unhelpful ways without it: clipboard
+ * tools exit before reading their input, so the write fails with `EPIPE`.
  */
-functionisClipboardAvailable(env: NodeJS.ProcessEnv=process.env): boolean{
+functionhasDisplayServer(env: NodeJS.ProcessEnv=process.env): boolean{
 if(!DISPLAY_REQUIRED_PLATFORMS.has(process.platform)){
 returntrue
 }
 return!!(env.WSL_DISTRO_NAME||env.WAYLAND_DISPLAY||env.DISPLAY)
 }
 
-functioncenterBlock(block: string): string{
+functioncenterBlock(block: string,blockWidth?: number): string{
 constlines=block.split('\n')
-constwidth=Math.max(...lines.map(line=>line.length))
+constwidth=blockWidth??Math.max(...lines.map(line=>line.length))
 constcolumns=Math.min(process.stdout.columns||80,80)
 constindent=' '.repeat(Math.max(0,Math.floor((columns-width)/2)))
 returnlines.map(line=>indent+line).join('\n')
@@ -342,16 +344,41 @@ export function resolveOpenCommand(
 return['xdg-open',[url]]
 }
 
+/** How long a launcher has to fail before we assume the browser did open. */
+constBROWSER_LAUNCH_TIMEOUT_MS=3000
+
 exportfunctionopenBrowser(url: string): void{
 constresolved=resolveOpenCommand(url)
 if(!resolved){
 return
 }
+if(!hasDisplayServer()){
+logger.warn(`No browser is available in this environment. Open ${colors.cyan(url)} manually.`)
+return
+}
+
 const[command,args]=resolved
+constonFailure=(error: unknown)=>{
+debug('Failed to open browser:',error)
+logger.warn(`Could not open ${colors.cyan(url)} in a browser.`)
+}
+
 try{
-spawn(command,args,{stdio: 'ignore',detached: true}).on('error',error=>debug('Failed to open browser:',error)).unref()
+constchild=spawn(command,args,{stdio: 'ignore',detached: true})
+child.once('error',onFailure)
+constonExit=(code: number|null)=>{
+if(code){
+onFailure(newError(`\`${command}\` exited with code ${code}`))
+}
+}
+child.once('exit',onExit)
+// `BROWSER` may point at the browser itself rather than a launcher, in which
+// case the process lives as long as the browser does and its eventual exit
+// code says nothing about whether the URL opened.
+setTimeout(()=>child.off('exit',onExit),BROWSER_LAUNCH_TIMEOUT_MS).unref()
+child.unref()
 }
 catch(error){
-debug('Failed to open browser:',error)
+onFailure(error)
 }
 }

packages/nuxt-cli/src/dev/shortcuts.ts

@@ -47,7 +47,7 @@ const shortcuts: Shortcut[] = [
 {
 keys: ['qr'],
 description: 'show a QR code for the server URL',
-action: context=>printQRCode(resolveShareableURL(context.listener)),
+action: context=>printQRCode(resolveShareableURL(context.listener),{showURL: true}),
 },
 {
 keys: ['copy'],

packages/nuxt-cli/test/unit/listen.spec.ts

@@ -2,15 +2,19 @@ import type { Listener } from '../../src/dev/listen'
 
 import{networkInterfaces}from'node:os'
 
-import{afterEach,describe,expect,it,vi}from'vitest'
+import{afterEach,beforeEach,describe,expect,it,vi}from'vitest'
 
-import{copyURL,getNetworkAddresses,listen,resolveOpenCommand}from'../../src/dev/listen'
+import{copyURL,getNetworkAddresses,listen,openBrowser,resolveOpenCommand}from'../../src/dev/listen'
 
 constwriteText=vi.hoisted(()=>vi.fn())
 
 vi.mock('tinyclip',()=>({ writeText }))
 
-constspawn=vi.hoisted(()=>vi.fn((_command: string,_args: string[])=>({on: ()=>({unref: ()=>{}})})))
+constspawn=vi.hoisted(()=>vi.fn((_command: string,_args: string[])=>({
+once: ()=>{},
+off: ()=>{},
+unref: ()=>{},
+})))
 
 vi.mock('node:child_process',()=>({ spawn }))
 
@@ -21,6 +25,20 @@ vi.mock('node:os', () => ({
 
 constmocked=vi.mocked(networkInterfaces)
 
+constrealPlatform=process.platform
+constrealEnv={ ...process.env}
+
+/** Pretend to run on `platform`, with only the display variables in `env` set. */
+functionstubEnvironment(platform: NodeJS.Platform,env: NodeJS.ProcessEnv={}){
+Object.defineProperty(process,'platform',{value: platform,configurable: true})
+process.env={ ...realEnv,DISPLAY: undefined,WAYLAND_DISPLAY: undefined,WSL_DISTRO_NAME: undefined, ...env}
+}
+
+functionrestoreEnvironment(){
+Object.defineProperty(process,'platform',{value: realPlatform,configurable: true})
+process.env={ ...realEnv}
+}
+
 describe('getNetworkAddresses',()=>{
 it('should return external IPv4 addresses',()=>{
 mocked.mockReturnValue({
@@ -76,7 +94,11 @@ describe('resolveOpenCommand', () => {
 describe('listen',()=>{
 constlisteners: Listener[]=[]
 
+// `openBrowser` refuses to spawn a launcher without a graphical session.
+beforeEach(()=>stubEnvironment(realPlatform,{DISPLAY: ':0'}))
+
 afterEach(async()=>{
+restoreEnvironment()
 awaitPromise.all(listeners.splice(0).map(listener=>listener.close()))
 })
 
@@ -124,48 +146,62 @@ describe('listen', () => {
 })
 
 describe('copyURL',()=>{
-constplatform=process.platform
-constenv={ ...process.env}
-
 afterEach(()=>{
-Object.defineProperty(process,'platform',{value: platform,configurable: true})
-process.env={ ...env}
+restoreEnvironment()
 vi.clearAllMocks()
 })
 
-functionstubPlatform(value: NodeJS.Platform,overrides: NodeJS.ProcessEnv={}){
-Object.defineProperty(process,'platform',{ value,configurable: true})
-process.env={ ...env,DISPLAY: undefined,WAYLAND_DISPLAY: undefined,WSL_DISTRO_NAME: undefined, ...overrides}
-}
-
 it('should skip copying without a display server on linux',async()=>{
-stubPlatform('linux')
+stubEnvironment('linux')
 
 awaitcopyURL('http://localhost:3000/')
 
 expect(writeText).not.toHaveBeenCalled()
 })
 
 it('should copy when a display server is available',async()=>{
-stubPlatform('linux',{DISPLAY: ':0'})
+stubEnvironment('linux',{DISPLAY: ':0'})
 
 awaitcopyURL('http://localhost:3000/')
 
 expect(writeText).toHaveBeenCalledWith('http://localhost:3000/')
 })
 
 it('should copy on platforms that do not need a display server',async()=>{
-stubPlatform('darwin')
+stubEnvironment('darwin')
 
 awaitcopyURL('http://localhost:3000/')
 
 expect(writeText).toHaveBeenCalledWith('http://localhost:3000/')
 })
 
 it('should warn rather than throw when copying fails',async()=>{
-stubPlatform('darwin')
+stubEnvironment('darwin')
 writeText.mockRejectedValueOnce(newError('no clipboard tool found'))
 
 awaitexpect(copyURL('http://localhost:3000/')).resolves.toBeUndefined()
 })
 })
+
+describe('openBrowser',()=>{
+afterEach(()=>{
+restoreEnvironment()
+vi.clearAllMocks()
+})
+
+it('should not spawn a launcher without a display server',()=>{
+stubEnvironment('linux')
+
+openBrowser('http://localhost:3000/')
+
+expect(spawn).not.toHaveBeenCalled()
+})
+
+it('should spawn a launcher when a display server is available',()=>{
+stubEnvironment('linux',{DISPLAY: ':0'})
+
+openBrowser('http://localhost:3000/')
+
+expect(spawn).toHaveBeenCalledWith('xdg-open',['http://localhost:3000/'],expect.anything())
+})
+})

packages/nuxt-cli/test/unit/shortcuts.spec.ts

@@ -100,7 +100,7 @@ describe('setupShortcuts', () => {
 const{ press }=setup({ close })
 
 awaitpress('qr')
-awaitvi.waitFor(()=>expect(printQRCode).toHaveBeenCalledWith('http://localhost:3000/'))
+awaitvi.waitFor(()=>expect(printQRCode).toHaveBeenCalledWith('http://localhost:3000/',{showURL: true}))
 expect(close).not.toHaveBeenCalled()
 
 awaitpress('q')