@weft-js/cli 0.1.1 → 0.1.2

package/src/browser/client.mjs

@@ -13,7 +13,9 @@ export async function devUrl(root, given) {
   if (given) return given.replace(/\/$/, '')
   const file = join(root, '.weft', 'dev.json')
   if (existsSync(file)) {
-    try { return JSON.parse(readFileSync(file, 'utf8')).url.replace(/\/$/, '') } catch {}
+    try {
+      return JSON.parse(readFileSync(file, 'utf8')).url.replace(/\/$/, '')
+    } catch {}
   }
   const { config } = await loadConfig(root).catch(() => ({ config: {} }))
   return (config.environments?.dev?.url ?? 'http://localhost:5173').replace(/\/$/, '')
@@ -23,8 +25,15 @@ const fail = (code, message, extra) => Object.assign(new Error(message), { code,
 
 async function request(url, init) {
   try {
-    const res = await fetch(`${url}/__weft/agent`, { ...init, headers: { 'x-weft-agent': '1', 'content-type': 'application/json' } })
-    if (res.status === 404) throw fail('E_NO_BRIDGE', `${url} is not a weft dev server (no /__weft/agent): serve the app with the weft() Vite plugin`)
+    const res = await fetch(`${url}/__weft/agent`, {
+      ...init,
+      headers: { 'x-weft-agent': '1', 'content-type': 'application/json' },
+    })
+    if (res.status === 404)
+      throw fail(
+        'E_NO_BRIDGE',
+        `${url} is not a weft dev server (no /__weft/agent): serve the app with the weft() Vite plugin`,
+      )
     return await res.json()
   } catch (e) {
     if (e.code) throw e
@@ -35,7 +44,10 @@ async function request(url, init) {
 /** Run one command in a tab (the focused one, else the most recent). */
 export async function call(root, cmd, args = {}, { url, tab, timeout } = {}) {
   const base = await devUrl(root, url)
-  const out = await request(base, { method: 'POST', body: JSON.stringify({ cmd, args, tab, timeout }) })
+  const out = await request(base, {
+    method: 'POST',
+    body: JSON.stringify({ cmd, args, tab, timeout }),
+  })
   if (!out.ok) throw fail(out.code ?? 'E_PAGE', out.error, { tabs: out.tabs })
   return out.result
 }
@@ -47,55 +59,195 @@ export async function tabs(root, { url } = {}) {
 }
 
 /** Wait until a tab is connected (after `launch` or `navigate`). */
-export async function waitForTab(root, { url, ms = 15_000 } = {}) {
+export async function waitForTab(root, { url, ms = 15_000, check } = {}) {
   const until = Date.now() + ms
   for (;;) {
+    check?.()
+    let connected
     try {
-      const t = await tabs(root, { url })
-      if (t.tabs.length) return t
-    } catch (e) { if (Date.now() > until) throw e }
+      connected = await tabs(root, { url })
+    } catch (e) {
+      if (Date.now() > until) throw e
+    }
+    check?.()
+    if (connected?.tabs.length) return connected
     if (Date.now() > until) throw fail('E_NO_TAB', 'no tab connected in time')
-    await new Promise(r => { setTimeout(r, 150) })
+    await new Promise((r) => {
+      setTimeout(r, 150)
+    })
   }
 }
 
 // ---- a host page when the agent has no browser ------------------------------------------------------------------
 
 const chromes = {
-  darwin: ['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/Applications/Chromium.app/Contents/MacOS/Chromium', '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'],
-  linux: ['/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser', '/snap/bin/chromium'],
-  win32: ['C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe', 'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe'],
+  darwin: [
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  ],
+  linux: [
+    '/usr/bin/google-chrome',
+    '/usr/bin/google-chrome-stable',
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+    '/snap/bin/chromium',
+  ],
+  win32: [
+    'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+    'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+  ],
 }
 
 export function findChrome() {
   const env = process.env.WEFT_CHROME ?? process.env.CHROME_PATH
   if (env && existsSync(env)) return env
-  return (chromes[process.platform] ?? []).find(p => existsSync(p)) ?? null
+  return (chromes[process.platform] ?? []).find((p) => existsSync(p)) ?? null
 }
 
-const stateFile = root => join(root, '.weft', 'browser', 'chrome.json')
+const stateFile = (root) => join(root, '.weft', 'browser', 'chrome.json')
+
+// Report only URL structure, never credentials, query parameters or fragments.
+function safeUrl(value) {
+  try {
+    const url = new URL(value)
+    url.username = ''
+    url.password = ''
+    url.search = ''
+    url.hash = ''
+    return url.href.slice(0, 500)
+  } catch {
+    return '[invalid URL]'
+  }
+}
 
-/** Start a headless Chrome on `route` (a plain page; @weft-js/core/agent in it connects back to the dev server). */
+async function devtoolsJson(port, path, signal) {
+  const response = await fetch(`http://127.0.0.1:${port}${path}`, { signal })
+  if (!response.ok || !response.body) throw new Error('DevTools endpoint unavailable')
+  const reader = response.body.getReader()
+  const chunks = []
+  let size = 0
+  try {
+    for (;;) {
+      const { value, done } = await reader.read()
+      if (done) break
+      size += value.length
+      if (size > 32_768) throw new Error('DevTools response too large')
+      chunks.push(value)
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+  } finally {
+    await reader.cancel().catch(() => {})
+  }
+}
+
+/** Append bounded, failure-only DevTools evidence without replacing the launch error. */
+export async function diagnoseLaunch(error, profile, expected) {
+  try {
+    const port = readFileSync(join(profile, 'DevToolsActivePort'), 'utf8').split('\n')[0]
+    if (!/^\d{1,5}$/.test(port) || +port < 1 || +port > 65535) throw new Error('invalid port')
+    const signal = AbortSignal.timeout(750)
+    const [version, targets] = await Promise.all([
+      devtoolsJson(port, '/json/version', signal).catch(() => null),
+      devtoolsJson(port, '/json/list', signal).catch(() => null),
+    ])
+    const browser =
+      typeof version?.Browser === 'string'
+        ? (version.Browser.match(/^(?:Chrome|Chromium|HeadlessChrome|Edg)\/[0-9.]+/)?.[0] ??
+          'unavailable')
+        : 'unavailable'
+    const pages = Array.isArray(targets)
+      ? targets
+          .filter((target) => target?.type === 'page')
+          .slice(0, 10)
+          .map((target) => ({
+            url: safeUrl(target.url),
+            state:
+              typeof target.attached === 'boolean'
+                ? target.attached
+                  ? 'attached'
+                  : 'not attached'
+                : target.webSocketDebuggerUrl
+                  ? 'debuggable'
+                  : 'no debugger',
+          }))
+      : 'unavailable'
+    error.message += `; DevTools: ${JSON.stringify({ browser, expected: safeUrl(expected), pages })}`
+  } catch {
+    error.message += `; DevTools unavailable; expected: ${safeUrl(expected)}`
+  }
+  return error
+}
+
+/**
+ * Start a headless Chrome on `route` (a plain page; @weft-js/core/agent connects back to the dev server).
+ * @param {string} root
+ * @param {string} [route]
+ * @param {{ url?: string | undefined, headed?: boolean | undefined }} [options]
+ */
 export async function launch(root, route = '/', { url, headed = false } = {}) {
   const exe = findChrome()
-  if (!exe) throw fail('E_NO_CHROME', 'no Chrome or Chromium found; open the app in your own browser instead, or set WEFT_CHROME')
+  if (!exe)
+    throw fail(
+      'E_NO_CHROME',
+      'no Chrome or Chromium found; open the app in your own browser instead, or set WEFT_CHROME',
+    )
   close(root)
   const base = await devUrl(root, url)
   const profile = join(root, '.weft', 'browser', 'profile')
   mkdirSync(profile, { recursive: true })
-  const args = [`--user-data-dir=${profile}`, '--remote-debugging-port=0', '--no-first-run', '--no-default-browser-check', '--disable-background-timer-throttling', '--disable-renderer-backgrounding', ...(headed ? [] : ['--headless=new']), ...(process.getuid?.() === 0 ? ['--no-sandbox'] : []) /* Chrome won't start as root with its sandbox: a container, CI */, `${base}${route.startsWith('/') ? route : `/${route}`}`]
-  const child = spawn(exe, args, { detached: true, stdio: 'ignore' })
+  const args = [
+    `--user-data-dir=${profile}`,
+    '--remote-debugging-port=0',
+    '--no-first-run',
+    '--no-default-browser-check',
+    '--disable-background-timer-throttling',
+    '--disable-renderer-backgrounding',
+    ...(headed ? [] : ['--headless=new']),
+    ...(process.getuid?.() === 0
+      ? ['--no-sandbox']
+      : []) /* Chrome won't start as root with its sandbox: a container, CI */,
+    `${base}${route.startsWith('/') ? route : `/${route}`}`,
+  ]
+  const child = spawn(exe, args, { detached: true, stdio: ['ignore', 'ignore', 'pipe'] })
+  let stderr = '',
+    failure = null
+  child.stderr.on('data', (chunk) => {
+    stderr = (stderr + chunk.toString()).slice(-4096)
+  })
+  child.on('error', (error) => {
+    failure = `spawn: ${error.message}`
+  })
+  child.on('exit', (code, signal) => {
+    failure = `exit: ${code}, signal: ${signal}`
+  })
   child.unref()
+  child.stderr.unref?.()
   writeFileSync(stateFile(root), JSON.stringify({ pid: child.pid, profile, exe }))
-  const t = await waitForTab(root, { url })
-  return { launched: true, pid: child.pid, headless: !headed, ...t }
+  try {
+    const t = await waitForTab(root, {
+      url,
+      check: () => {
+        if (failure) throw fail('E_CHROME', `Chrome ${failure}; stderr: ${stderr}`)
+      },
+    })
+    return { launched: true, pid: child.pid, headless: !headed, ...t }
+  } catch (error) {
+    await diagnoseLaunch(error, profile, args.at(-1))
+    close(root)
+    child.stderr.destroy()
+    error.message += ` (Chrome ${failure ?? 'still running'}; stderr: ${stderr})`
+    throw error
+  }
 }
 
 export function close(root) {
   const file = stateFile(root)
   if (!existsSync(file)) return { closed: false }
   const { pid } = JSON.parse(readFileSync(file, 'utf8'))
-  try { process.kill(pid) } catch {}
+  try {
+    process.kill(pid)
+  } catch {}
   rmSync(file, { force: true })
   return { closed: true, pid }
 }
@@ -103,16 +255,28 @@ export function close(root) {
 /** A PNG of the launched Chrome's page (DevTools protocol). An agent's own browser takes its own screenshots. */
 export async function screenshot(root, out) {
   const file = stateFile(root)
-  if (!existsSync(file)) throw fail('E_NO_CHROME', 'screenshot needs `weft browser launch`; in your own browser, use its screenshot tool')
+  if (!existsSync(file))
+    throw fail(
+      'E_NO_CHROME',
+      'screenshot needs `weft browser launch`; in your own browser, use its screenshot tool',
+    )
   const { profile } = JSON.parse(readFileSync(file, 'utf8'))
   const [port] = readFileSync(join(profile, 'DevToolsActivePort'), 'utf8').split('\n')
   const targets = await (await fetch(`http://127.0.0.1:${port}/json`)).json()
-  const page = targets.find(t => t.type === 'page')
+  const page = targets.find((t) => t.type === 'page')
   if (!page) throw fail('E_NO_TAB', 'the launched Chrome has no page')
   const ws = new WebSocket(page.webSocketDebuggerUrl)
-  await new Promise((ok, no) => { ws.onopen = ok; ws.onerror = () => no(fail('E_CDP', 'could not reach the page over the DevTools protocol')) })
+  await new Promise((ok, no) => {
+    ws.onopen = ok
+    ws.onerror = () => no(fail('E_CDP', 'could not reach the page over the DevTools protocol'))
+  })
   const data = await new Promise((ok, no) => {
-    ws.onmessage = e => { const m = JSON.parse(e.data); if (m.id !== 1) return; if (m.error) no(fail('E_CDP', m.error.message)); else ok(m.result.data) }
+    ws.onmessage = (e) => {
+      const m = JSON.parse(e.data)
+      if (m.id !== 1) return
+      if (m.error) no(fail('E_CDP', m.error.message))
+      else ok(m.result.data)
+    }
     ws.send(JSON.stringify({ id: 1, method: 'Page.captureScreenshot', params: { format: 'png' } }))
   })
   ws.close()

package/src/browser/commands.mjs

@@ -1,14 +1,41 @@
 // `weft browser` commands, shared by the CLI and the `weft mcp` browser tools. Each takes structured params and
-// returns JSON; the page side is @weft-js/core/agent (packages/weft/src/agent.ts).
+// returns JSON; the page side is @weft-js/core/agent (packages/core/src/agent.ts).
 
 import { mkdirSync, writeFileSync } from 'node:fs'
 import { dirname, isAbsolute, join } from 'node:path'
 import { call, close, launch, screenshot, spill, tabs, waitForTab } from './client.mjs'
 
-export const actions = ['click', 'dblclick', 'hover', 'focus', 'clear', 'fill', 'type', 'press', 'select', 'check', 'uncheck']
-export const expectations = ['visible', 'absent', 'text', 'exactText', 'value', 'checked', 'unchecked', 'disabled', 'enabled', 'focused', 'count']
+export const actions = [
+  'click',
+  'dblclick',
+  'hover',
+  'focus',
+  'clear',
+  'fill',
+  'type',
+  'press',
+  'select',
+  'check',
+  'uncheck',
+]
+export const expectations = [
+  'visible',
+  'absent',
+  'text',
+  'exactText',
+  'value',
+  'checked',
+  'unchecked',
+  'disabled',
+  'enabled',
+  'focused',
+  'count',
+]
 
-const sleep = ms => new Promise(r => { setTimeout(r, ms) })
+const sleep = (ms) =>
+  new Promise((r) => {
+    setTimeout(r, ms)
+  })
 
 /**
  * @param {string} root project root
@@ -19,42 +46,54 @@ const sleep = ms => new Promise(r => { setTimeout(r, ms) })
 export async function browser(root, cmd, p = {}, o = {}) {
   const page = (name, args, extra) => call(root, name, args, { ...o, ...extra })
   switch (cmd) {
-    case 'tabs': return tabs(root, o)
-    case 'launch': return launch(root, p.route ?? '/', { url: o.url, headed: p.headed })
-    case 'close': return close(root)
-    case 'open': {
-      const before = await page('info', {})
-      await page('navigate', { to: p.route ?? '/' })
-      // Same tab id after the load (@weft-js/core/agent keeps it in sessionStorage); wait for the new document to say hello.
-      const until = Date.now() + 15_000
-      do {
-        await sleep(150)
-        try {
-          const info = await page('info', {}, { timeout: 2000 })
-          if (info.url !== before.url || p.route === new URL(before.url).pathname) return info
-        } catch {}
-      } while (Date.now() <= until)
-      return waitForTab(root, o)
-    }
+    case 'tabs':
+      return tabs(root, o)
+    case 'launch':
+      return launch(root, p.route ?? '/', { url: o.url, headed: p.headed })
+    case 'close':
+      return close(root)
+    case 'open':
+      return await openPage(root, p, o, page)
     case 'snapshot': {
-      const out = await page('snapshot', { interactive: p.interactive, scope: p.scope, delta: p.delta, graph: p.graph })
+      const out = await page('snapshot', {
+        interactive: p.interactive,
+        scope: p.scope,
+        delta: p.delta,
+        graph: p.graph,
+      })
       if (!p.full) {
         if (out.tree) out.tree = spill(root, 'snapshot', out.tree)
         if (out.graph) out.graph = spill(root, 'graph', out.graph)
       }
       return out
     }
-    case 'act': return page('act', { target: p.target, action: p.action, value: p.value })
-    case 'assert': return page('assert', { target: p.target, expect: p.expect, timeout: p.timeout })
+    case 'act':
+      return page('act', { target: p.target, action: p.action, value: p.value })
+    case 'assert':
+      return page('assert', { target: p.target, expect: p.expect, timeout: p.timeout })
     case 'graph': {
       const out = await page('graph', { filter: p.filter })
-      return { graph: p.full ? out.graph : spill(root, 'graph', out.graph), nodes: out.nodes.length }
+      return {
+        graph: p.full ? out.graph : spill(root, 'graph', out.graph),
+        nodes: out.nodes.length,
+      }
     }
-    case 'set': return page('set', { name: p.name, value: p.value })
-    case 'time': return page('time', { op: p.op, ms: p.ms, reload: p.reload })
-    case 'net': return page('net', { op: p.op, ms: p.ms })
+    case 'set':
+      return page('set', { name: p.name, value: p.value })
+    case 'time':
+      return page('time', { op: p.op, ms: p.ms, reload: p.reload })
+    case 'net':
+      return page('net', { op: p.op, ms: p.ms })
     case 'record': {
-      const out = await page('record', { op: p.op, text: p.text, component: p.component, from: p.from, props: p.props, imports: p.imports, name: p.name })
+      const out = await page('record', {
+        op: p.op,
+        text: p.text,
+        component: p.component,
+        from: p.from,
+        props: p.props,
+        imports: p.imports,
+        name: p.name,
+      })
       if (p.op === 'code' && p.out) {
         const file = isAbsolute(p.out) ? p.out : join(root, p.out)
         mkdirSync(dirname(file), { recursive: true })
@@ -63,61 +102,137 @@ export async function browser(root, cmd, p = {}, o = {}) {
       }
       return out
     }
-    case 'logs': return page('logs', {})
-    case 'overlay': return page('overlay', { show: p.show })
-    case 'info': return page('info', {})
-    case 'reload': return page('reload', {})
-    case 'screenshot': return screenshot(root, p.out && (isAbsolute(p.out) ? p.out : join(root, p.out)))
+    case 'logs':
+      return page('logs', {})
+    case 'overlay':
+      return page('overlay', { show: p.show })
+    case 'info':
+      return page('info', {})
+    case 'reload':
+      return page('reload', {})
+    case 'screenshot':
+      return screenshot(root, p.out && (isAbsolute(p.out) ? p.out : join(root, p.out)))
     default:
       throw Object.assign(new Error(`unknown browser command ${cmd}`), { code: 'E_USAGE' })
   }
 }
 
+async function openPage(root, p, o, page) {
+  const before = await page('info', {})
+  await page('navigate', { to: p.route ?? '/' })
+  // Same tab id after the load (@weft-js/core/agent keeps it in sessionStorage); wait for the new document to say hello.
+  const until = Date.now() + 15_000
+  do {
+    await sleep(150)
+    try {
+      const info = await page('info', {}, { timeout: 2000 })
+      if (info.url !== before.url || p.route === new URL(before.url).pathname) return info
+    } catch {}
+  } while (Date.now() <= until)
+  return waitForTab(root, o)
+}
+
 /** `button "Add Banana"`, `label Coupon`, `text Cart`, `@e5` → a target, and how many words it took. */
 export function parseTarget(words) {
   const [a, b] = words
-  if (!a) throw Object.assign(new Error('missing target: <role> <name>, label <text>, text <text>, or @ref'), { code: 'E_USAGE' })
+  if (!a)
+    throw Object.assign(
+      new Error('missing target: <role> <name>, label <text>, text <text>, or @ref'),
+      { code: 'E_USAGE' },
+    )
   if (a.startsWith('@')) return [a, 1]
   if (a === 'label') return [{ label: b }, 2]
   if (a === 'text') return [{ text: b }, 2]
-  return [b === undefined || b === '-' ? { role: a } : { role: a, name: b }, b === undefined ? 1 : 2]
+  return [
+    b === undefined || b === '-' ? { role: a } : { role: a, name: b },
+    b === undefined ? 1 : 2,
+  ]
 }
 
 /** CLI words → params. */
 export function cliParams(cmd, words, flags) {
-  const num = v => (v === undefined ? undefined : Number(v))
+  const num = (v) => (v === undefined ? undefined : Number(v))
   switch (cmd) {
-    case 'launch': case 'open': return { route: words[0] ?? '/', headed: !!flags.headed }
-    case 'snapshot': return { interactive: !!flags.interactive, delta: !!flags.delta, graph: flags['graph-only'] ? 'only' : flags['no-graph'] ? false : flags.graph ?? true, scope: flags.scope ? parseScope(flags.scope) : undefined, full: !!flags.full }
+    case 'launch':
+    case 'open':
+      return { route: words[0] ?? '/', headed: !!flags.headed }
+    case 'snapshot':
+      return {
+        interactive: !!flags.interactive,
+        delta: !!flags.delta,
+        graph: flags['graph-only'] ? 'only' : flags['no-graph'] ? false : (flags.graph ?? true),
+        scope: flags.scope ? parseScope(flags.scope) : undefined,
+        full: !!flags.full,
+      }
     case 'act': {
       const [target, n] = parseTarget(words)
       const action = words[n] ?? 'click'
-      if (!actions.includes(action)) throw Object.assign(new Error(`unknown action ${action}: ${actions.join(', ')}`), { code: 'E_USAGE' })
+      if (!actions.includes(action))
+        throw Object.assign(new Error(`unknown action ${action}: ${actions.join(', ')}`), {
+          code: 'E_USAGE',
+        })
       return { target, action, value: words[n + 1] }
     }
     case 'assert': {
       const [target, n] = parseTarget(words)
       const kind = words[n] ?? 'visible'
-      if (!expectations.includes(kind)) throw Object.assign(new Error(`unknown expectation ${kind}: ${expectations.join(', ')}`), { code: 'E_USAGE' })
+      if (!expectations.includes(kind))
+        throw Object.assign(new Error(`unknown expectation ${kind}: ${expectations.join(', ')}`), {
+          code: 'E_USAGE',
+        })
       const v = words[n + 1]
-      return { target, expect: { [kind]: kind === 'count' ? Number(v) : ['text', 'exactText', 'value'].includes(kind) ? v ?? '' : true }, timeout: num(flags.timeout) }
+      return {
+        target,
+        expect: {
+          [kind]:
+            kind === 'count'
+              ? Number(v)
+              : ['text', 'exactText', 'value'].includes(kind)
+                ? (v ?? '')
+                : true,
+        },
+        timeout: num(flags.timeout),
+      }
     }
-    case 'graph': return { filter: words[0], full: !!flags.full }
+    case 'graph':
+      return { filter: words[0], full: !!flags.full }
     case 'set': {
       let value = words[1]
-      try { value = JSON.parse(words[1]) } catch {}
+      try {
+        value = JSON.parse(words[1])
+      } catch {}
       return { name: words[0], value }
     }
-    case 'time': return { op: words[0] ?? 'status', ms: num(words[1]), reload: !!flags.reload }
-    case 'net': return { op: words[0] ?? 'status', ms: num(words[1]) }
-    case 'record': return { op: words[0] ?? 'code', text: words.slice(1).join(' '), component: flags.component, from: flags.from, props: flags.props, name: flags.name, out: flags.out }
-    case 'overlay': return { show: words[0] === undefined ? undefined : words[0] !== 'off' }
-    case 'screenshot': return { out: flags.out }
-    default: return {}
+    case 'time':
+      return { op: words[0] ?? 'status', ms: num(words[1]), reload: !!flags.reload }
+    case 'net':
+      return { op: words[0] ?? 'status', ms: num(words[1]) }
+    case 'record':
+      return {
+        op: words[0] ?? 'code',
+        text: words.slice(1).join(' '),
+        component: flags.component,
+        from: flags.from,
+        props: flags.props,
+        name: flags.name,
+        out: flags.out,
+      }
+    case 'overlay':
+      return { show: words[0] === undefined ? undefined : words[0] !== 'off' }
+    case 'screenshot':
+      return { out: flags.out }
+    default:
+      return {}
   }
 }
 
-const parseScope = s => (s.startsWith('@') ? s : (() => { const i = s.indexOf(':'); return i < 0 ? { role: s } : { role: s.slice(0, i), name: s.slice(i + 1) } })())
+const parseScope = (s) =>
+  s.startsWith('@')
+    ? s
+    : (() => {
+        const i = s.indexOf(':')
+        return i < 0 ? { role: s } : { role: s.slice(0, i), name: s.slice(i + 1) }
+      })()
 
 export const browserUsage = `usage: weft browser <command> [--json] [--url <dev server>] [--tab <id>]