@surph_ai/cli 0.0.26 → 0.0.27

package/cli.js

@@ -12,7 +12,6 @@ const fs = require('fs')
 const os = require('os')
 const http = require('http')
 const crypto = require('crypto')
-const { exec } = require('child_process')
 const dotenv = require('dotenv')
 const prompt = require('prompt')
 const shell = require('shelljs')
@@ -23,6 +22,8 @@ const deploy = require('./deploy')
 const scaffold = require('./scaffold')
 const { ensureChat, chatNodePath } = require('./toolserver/ensure-chat')
 const utils = require('./utils')
+const { openBrowser, openBrowserWhenReady } = require('./utils/browser')
+const { prepareWindowsConsole } = require('./utils/windowsConsole')
 const packageJson = require('./package.json')
 
 const VERSION = packageJson.version
@@ -68,20 +69,6 @@ const surphSession = async () => {
   }
 }
 
-// Cross-platform browser opener. Falls back to printing the URL — matters for
-// SSH / headless / broken default handlers, where `open` silently no-ops.
-const openBrowser = (url) => {
-  const cmd = process.platform === 'darwin' ? `open "${url}"`
-    : process.platform === 'win32' ? `start "" "${url}"`
-    : `xdg-open "${url}"`
-  exec(cmd, (err) => {
-    if (err) {
-      console.log(colors.yellow(`\nCouldn't open browser automatically. Open this URL manually:\n`))
-      console.log(colors.cyan(url) + '\n')
-    }
-  })
-}
-
 const loginSuccessHtml = (username) => `<!doctype html>
 <html>
 <head><meta charset="utf-8"><title>Surph — Logged in</title>
@@ -273,50 +260,6 @@ program.command('profile')
   // console.log(text)
 })
 
-/*
-program.command('login')
-.description('login to Surph')
-.action(async (cmd, options) => {
-  try {
-    const credentials = await auth.showPrompt()
-
-    const resp = await axios({
-      url: `${PORTAL_URL}/auth/login`,
-      method: 'post',
-      data: credentials,
-      headers: { Accept: 'application/json'}
-    })
-
-    const { data } = resp.data
-		const user = { id: data._id, username: data.username }
-
-		shell.cd('')
-		utils.write('.Surph_user', JSON.stringify(user, null, 2) + '\n')
-
-    const successText = `${colors.cyan(`\nSuccess! `)} ${colors.brightGreen(`Currently Logged In As ${user.username}\n`)}`
-    console.log(successText)
-  } catch (error) {
-    utils.printError(error)
-  }
-})
-
-program.command('dev')
-.description('run dev server')
-.action(async (cmd, options) => {
-  try {
-  	// shell.cp('-R', path.join(__dirname, '../default/lambda/js/index.js'), 'vectors/js/index.js')
-		shell.cd(path.join(__dirname, 'base/Surph-base'))
-    shell.exec('npm run dev')
-		// shell.cd('Surph-base')
-
-    // shell.exec('gulp build --gulpfile node_modules/@turbo360/turbo-sdk/src/gulpfile.js --silent')
-
-  } catch (error) {
-    utils.printError(error)
-  }
-})
-*/
-
 program.command('new <name>')
 .description('create new Surph app')
 .action(name => scaffold(name, 'project'))
@@ -404,7 +347,17 @@ program.command('manifest')
 
 program.command('browser <url>')
 .description('open browser to url')
-.action(url => openBrowser(url))
+.option('--timeout <seconds>', 'how long to wait for a local server before giving up', '60')
+.option('--no-wait', 'open immediately instead of waiting for the port to accept connections')
+.action(async (url, options) => {
+  const seconds = Number(options.timeout)
+  const timeout = Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : 60000
+  if (options.wait === false) {
+    await openBrowser(url)
+    return
+  }
+  await openBrowserWhenReady(url, { timeout })
+})
 
 /*
 program.command('connect')
@@ -578,7 +531,7 @@ program.command('publish')
     })
   
     const data = await resp.json()
-    console.log('\nSurph tool updated.')
+    console.log(`\nSurph tool updated. To view, visit:\n\nhttps://surph.ai/tool/${slug}\n`)
   } catch (error) {
     console.log(colors.red('\nError: '+error.message+'\n'))
   }
@@ -589,44 +542,6 @@ program.command('deploy')
 .description('Deploy to Surph')
 .action(async (cmd, options) => {
   try {
-    /*
-    const { type } = cmd
-    if (type !== 'default' && type !== 'static') {
-      const msg = colors.red(`\nError: Invalid deployment type ${type}.\n`) +
-        colors.white(`Please select type "static" or omit type flag.\n`);
-      program.error(msg, ERRORS.INVALID_PARAMS)
-    }
-
-    const user = await auth.currentUser() // must be logged in.
-    if (user === false) {
-      program.error(`${colors.cyan('\nNot logged in. To log in:')}\n\n${colors.white('$ vly login')}`,
-        ERRORS.NOT_LOGGED_IN);
-    }
-
-    */
-
-    /*
-    const apps = await Realm.restQuery('project', 'get', { slug: TURBO_PROJECT_SLUG })
-    if (apps.length === 0) {
-      program.error(`App ${TURBO_PROJECT} not found.`, ERRORS.PROJECT_NOT_FOUND)
-    }
-
-    const { members } = apps[0]
-    if (!members.find(member => (member.id === user.id))) {
-      program.error('Unauthorized', ERRORS.NOT_AUTHORIZED)
-    }
-    */
-
-    /*
-    const { SURPH_TOOL = null } = dotenv.parse(utils.readFile('.env') ?? '')
-
-    if (SURPH_TOOL === null) {
-      program.error('Surph project not connected. To connect, run:\n\n$ surph connect', ERRORS.PROJECT_NOT_CONNECTED)
-    }
-
-    await deploy.tool({ SURPH_TOOL_SLUG: SURPH_TOOL })
-    */
-
     const manifest = require('../../../manifest.json')
     if (!manifest) {
       throw new Error('manifest.json not found')
@@ -641,4 +556,8 @@ program.command('deploy')
   }
 })
 
+// Legacy Windows consoles block stdout while QuickEdit selection is active.
+// See utils/windowsConsole.js (SURPH_NO_CONSOLE_FIX=1 to skip).
+prepareWindowsConsole()
+
 program.parse(process.argv)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surph_ai/cli",
-  "version": "0.0.26",
+  "version": "0.0.27",
   "description": "",
   "main": "index.js",
   "types": "./types.d.ts",
@@ -20,6 +20,7 @@
     "adm-zip": "^0.5.10",
     "bestzip": "^2.2.1",
     "cheerio": "^1.2.0",
+    "cli-progress": "^3.12.0",
     "colors": "^1.4.0",
     "commander": "^14.0.1",
     "cookie": "^0.5.0",

package/scaffold/index.js

@@ -3,21 +3,28 @@ const shell = require('shelljs')
 const path = require('path')
 const fs = require('fs')
 const dotenv = require('dotenv')
+const colors = require('colors/safe')
 const utils = require('../utils')
+const { StepProgress } = require('../utils/progress')
+const { runCaptured } = require('../utils/command')
 
-// Cross-platform browser opener. Falls back to printing the URL — matters for
-// SSH / headless / broken default handlers, where `open` silently no-ops.
-const openBrowser = (url) => {
-  const cmd = process.platform === 'darwin' ? `open "${url}"`
-    : process.platform === 'win32' ? `start "" "${url}"`
-    : `xdg-open "${url}"`
-  exec(cmd, (err) => {
-    if (err) {
-      console.log(colors.yellow(`\nCouldn't open browser automatically. Open this URL manually:\n`))
-      console.log(colors.cyan(url) + '\n')
-    }
-  })
-}
+const CHEATSHEET_URL = 'https://surph.s3.us-east-1.amazonaws.com/tools/cli/CHEATSHEET.md'
+
+// Scaffold steps in order. `weight` is each step's share of overall progress (sum ≈ 100).
+const TOOL_STEPS = [
+  { id: 'directory', doing: 'Creating project directory', done: 'Project directory created', weight: 1 },
+  { id: 'package', doing: 'Writing package.json', done: 'package.json written', weight: 1 },
+  { id: 'examples', doing: 'Copying example tools', done: 'Example tools copied', weight: 2 },
+  { id: 'manifests', doing: 'Writing manifests', done: 'Manifests written', weight: 1 },
+  { id: 'config', doing: 'Writing .env and tsconfig.json', done: '.env and tsconfig.json written', weight: 1 },
+  { id: 'cheatsheet', doing: 'Fetching cheatsheet', done: 'Cheatsheet fetched', weight: 4 },
+  { id: 'install', doing: 'Installing dependencies', done: 'Dependencies installed', weight: 82 },
+  { id: 'devserver', doing: 'Starting dev server', done: 'Dev server starting', weight: 8 }
+]
+
+// Expected package count for install sub-progress; grows if the tree is larger.
+// Used as clamp for install sub-progress. Never shown to the user.
+const EXPECTED_PACKAGES = 324
 
 function generateRandomSuffix(length = 6) {
   const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
@@ -43,10 +50,6 @@ function slugify(text, randomLength = 8) {
   return slug;
 }
 
-// var PLATFORM_VECTOR_URL = 'https://platform.turbo360-vector.com'
-// var VERTEX_NPM_VERSION = "^0.30.25"
-// var TURBO_NPM_VERSION = "^1.8.69"
-
 const nextSteps = function(name){
 	console.log('\n- - - - - Next Steps - - - - - ')
 	console.log('1. $ cd ' + name)
@@ -57,28 +60,111 @@ const nextSteps = function(name){
 	console.log('For full documentation, visit https://docs.turbo360.co\n')
 }
 
+const manifestExample = {
+  name: 'youtube-transcript',
+  slug: 'y2script',
+  type: 'custom',
+  description: 'Fetch the plain-text transcript (spoken words) of a YouTube video. Use this whenever the user asks about, quotes from, summarizes, or wants to search inside the content of a YouTube video — including questions like "what does this video say about X", "summarize this video", "pull the transcript", or when the user pastes a YouTube URL and expects you to know its contents. Do NOT use this for non-YouTube videos (it will fail on other video sources).',
+  parameters: {
+    type: 'object',
+    properties: {
+      video: {
+        type: 'string',
+        description: 'The YouTube video to transcribe. Accepts either a full URL (e.g. "https://www.youtube.com/watch?v=EwusdkKUlwI", "https://youtu.be/EwusdkKUlwI") or the bare 11-character video id (e.g. "EwusdkKUlwI"). Extract this from the user\'s message when they paste a link.'
+      }
+    },
+    required: ['video']
+  }
+}
 
-module.exports = async (name, type = 'app') => {
-  /*
-  https://stackoverflow.com/questions/8683895/how-do-i-determine-the-current-operating-system-with-node-js
-  Returns the operating system platform. Possible values are 'darwin', 'freebsd', 'linux',
-  'sunos' or 'win32'. Returns the value of process.platform.
-  'darwin' == mac
-  'win32' == windows
-  */
+const tsConfig = {
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "outDir": "./dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["tools/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}
 
-	const { platform } = process
+// Capture npm output (not streamed). `--loglevel=info` emits per-package http lines for progress.
+const NPM_METADATA = /^npm (?:http fetch GET \d+|http cache) (?:.*@)?https?:\/\/[^/]+\/([^\s]+?)(?:\s|$)/
+const NPM_TARBALL = /\.tgz\b/
+const installDependencies = async (progress, cwd) => {
+  const startedAt = Date.now()
+  const resolved = new Set()
+  const fetched = new Set()
+  let sawAnySignal = false
 
-  if (type === 'tool') {
-    console.log('create tool: ' + name)
+  const read = (line) => {
+    const match = NPM_METADATA.exec(line)
+    if (match) {
+      sawAnySignal = true
+      if (NPM_TARBALL.test(line)) fetched.add(match[1])
+      else resolved.add(match[1])
+    }
+  }
+
+  const tick = () => {
+    const elapsed = Date.now() - startedAt
+
+    if (!sawAnySignal) {
+      progress.advance(0.9 * (1 - Math.exp(-elapsed / 45000)))
+      return
+    }
+
+    const denom = Math.max(EXPECTED_PACKAGES, resolved.size, fetched.size)
+
+    const resolveShare = Math.min(1, resolved.size / denom)
+    const fetchShare = Math.min(1, fetched.size / denom)
+    const signal = 0.5 * resolveShare + 0.5 * fetchShare
+
+    const floor = 0.85 * (1 - Math.exp(-elapsed / 60000))
+    const fraction = Math.min(0.97, Math.max(signal, floor))
+
+    progress.advance(fraction)
+  }
+
+  const ticker = setInterval(tick, 250)
+  try {
+    await runCaptured('npm', ['install', '--no-fund', '--no-audit', '--loglevel=info'], {
+      cwd,
+      onLine: read,
+      retain: (line) => !/^npm (?:http |verbose |silly |timing )/.test(line)
+    })
+  } finally {
+    clearInterval(ticker)
+  }
+}
+
+const scaffoldTool = async (name) => {
+  const progress = new StepProgress(TOOL_STEPS)
+  console.log(progress.paint(colors.cyan, `\nCreating Surph tool: ${name}\n`))
+  progress.start()
+
+  try {
+    progress.begin('directory')
     shell.mkdir('-p', name)
     shell.cd(name)
+    await progress.done()
 
+    progress.begin('package')
     const pkgJsonStr = utils.readFile(path.join(__dirname, 'tool/package.json'))
     const pkgJson = JSON.parse(pkgJsonStr)
     pkgJson.name = name
     utils.write('package.json', JSON.stringify(pkgJson, null, 2) + '\n')
+    await progress.done()
 
+    progress.begin('examples')
     shell.mkdir('-p', 'tools')
     shell.cp('-R', path.join(__dirname, `tool/tools/index.ts`), 'tools/index.ts')
 
@@ -92,31 +178,12 @@ module.exports = async (name, type = 'app') => {
     shell.mkdir('-p', 'examples/weather')
     shell.cp('-R', path.join(__dirname, `tool/examples/weather/index.ts`), 'examples/weather/index.ts')
     shell.cp('-R', path.join(__dirname, `tool/examples/weather/manifest.json`), 'examples/weather/manifest.json')
+    await progress.done()
 
-    // shell.mkdir('-p', 'examples/dealfinder')
-    // shell.cp('-R', path.join(__dirname, `tool/examples/dealfinder/index.ts`), 'examples/dealfinder/index.ts')
-    // shell.cp('-R', path.join(__dirname, `tool/examples/dealfinder/manifest.json`), 'examples/dealfinder/manifest.json')
-
-
-    utils.write('manifest-example.json', JSON.stringify({
-      name: 'youtube-transcript',
-      slug: 'y2script',
-      type: 'custom',
-      description: 'Fetch the plain-text transcript (spoken words) of a YouTube video. Use this whenever the user asks about, quotes from, summarizes, or wants to search inside the content of a YouTube video — including questions like "what does this video say about X", "summarize this video", "pull the transcript", or when the user pastes a YouTube URL and expects you to know its contents. Do NOT use this for non-YouTube videos (it will fail on other video sources).',
-      parameters: {
-        type: 'object',
-        properties: {
-          video: {
-            type: 'string',
-            description: 'The YouTube video to transcribe. Accepts either a full URL (e.g. "https://www.youtube.com/watch?v=EwusdkKUlwI", "https://youtu.be/EwusdkKUlwI") or the bare 11-character video id (e.g. "EwusdkKUlwI"). Extract this from the user\'s message when they paste a link.'
-          }
-        },
-        required: ['video']
-      }
-    } , null, 2) + '\n')
+    progress.begin('manifests')
+    utils.write('manifest-example.json', JSON.stringify(manifestExample, null, 2) + '\n')
 
     const slug = slugify(name, 8)
-
     const manifest = {}
     manifest[slug] = {
       name,
@@ -131,46 +198,61 @@ module.exports = async (name, type = 'app') => {
     }
 
     utils.write('manifest.json', JSON.stringify(manifest, null, 2) + '\n')
+    await progress.done()
 
+    progress.begin('config')
     const envStr = utils.readFile(path.join(__dirname, 'tool/env.txt'))
     utils.write('.env', envStr.replace('<SURPH_TOOL>', slug))
+    utils.write('tsconfig.json', JSON.stringify(tsConfig, null, 2) + '\n')
+    await progress.done()
 
-    const tsConfig = {
-      "compilerOptions": {
-        "target": "ES2022",
-        "module": "Node16",
-        "moduleResolution": "Node16",
-        "lib": ["ES2022"],
-        "types": ["node"],
-        "outDir": "./dist",
-        "rootDir": ".",
-        "strict": true,
-        "esModuleInterop": true,
-        "skipLibCheck": true,
-        "forceConsistentCasingInFileNames": true,
-        "resolveJsonModule": true
-      },
-      "include": ["tools/**/*.ts"],
-      "exclude": ["node_modules", "dist"]
+    progress.begin('cheatsheet')
+    try {
+      const cheatsheetResp = await fetch(CHEATSHEET_URL)
+      if (!cheatsheetResp.ok) {
+        throw new Error(`HTTP ${cheatsheetResp.status}`)
+      }
+      utils.write('CHEATSHEET.md', await cheatsheetResp.text())
+    } catch (error) {
+      // Cosmetic — a reference doc that didn't download is no reason to fail
+      // a scaffold that is otherwise complete.
+      progress.warn(`Could not fetch CHEATSHEET.md (${error.message}) - skipped.`)
     }
+    await progress.done()
 
-    utils.write('tsconfig.json', JSON.stringify(tsConfig, null, 2) + '\n')
+    progress.begin('install')
+    await installDependencies(progress, process.cwd())
+    await progress.done()
 
-    const cheatsheetResp = await fetch('https://surph.s3.us-east-1.amazonaws.com/tools/cli/CHEATSHEET.md')
-    utils.write('CHEATSHEET.md', await cheatsheetResp.text())
+    progress.begin('devserver')
+    await progress.complete()
+  } catch (error) {
+    progress.fail(error)
+    process.exitCode = 1
+    return
+  }
 
-    shell.cd(name)
-    shell.exec('npm install')
-    shell.exec('npm run dev')
-    openBrowser('http://localhost:6767')
-
-    console.log('\n- - - - - Next Steps - - - - - ')
-    console.log('Open codebase in a code editor and navigate to /tools/index.ts - this is where your tool code goes.')
-    console.log('\nFor full documentation, visit https://docs.surph.ai\n')
-    // console.log('1. $ cd ' + name)
-    // console.log('2. $ npm install or $ yarn install')
-    // console.log('3. $ npm run dev')
-    // console.log('4. Open http://localhost:6767 in a browser')
+  console.log('\n- - - - - Next Steps - - - - - ')
+  console.log('Open codebase in a code editor and navigate to /tools/index.ts - this is where your tool code goes.')
+  console.log('\nFor full documentation, visit https://docs.surph.ai\n')
+  console.log('Starting the dev server - your browser will open at http://localhost:6767')
+  console.log('To stop it, press Ctrl+C. To start it again, run: npm run dev\n')
 
+  shell.exec('npm run dev')
+}
+
+module.exports = async (name, type = 'app') => {
+  /*
+  https://stackoverflow.com/questions/8683895/how-do-i-determine-the-current-operating-system-with-node-js
+  Returns the operating system platform. Possible values are 'darwin', 'freebsd', 'linux',
+  'sunos' or 'win32'. Returns the value of process.platform.
+  'darwin' == mac
+  'win32' == windows
+  */
+
+	const { platform } = process
+
+  if (type === 'tool') {
+    await scaffoldTool(name)
   }
 }

package/scaffold/tool/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "npm run build && concurrently \"npm run watch\" \"surph toolserver\" \"surph chatserver\" \"surph browser 'http://localhost:6767'\"",
+    "dev": "npm run build && concurrently \"npm run watch\" \"surph toolserver\" \"surph chatserver\" \"surph browser http://localhost:6767\"",
     "test": "",
     "build": "rimraf dist && tsc",
     "watch": "tsc -w",

package/utils/browser.js

@@ -0,0 +1,153 @@
+const net = require('net')
+const { execFile } = require('child_process')
+const colors = require('colors/safe')
+
+// Windows' cmd.exe does not treat single quotes as quoting, so a dev script
+// written as `surph browser 'http://localhost:6767'` hands us a URL with the
+// quotes still attached. Projects scaffolded before this fix keep that script
+// and pull @surph_ai/cli@latest, so tolerating stray quotes here is what
+// repairs them on upgrade.
+const stripQuotes = (url) => {
+  let out = String(url == null ? '' : url).trim()
+  while (out.length >= 2) {
+    const first = out[0]
+    const last = out[out.length - 1]
+    if ((first === '"' || first === "'") && first === last) {
+      out = out.slice(1, -1).trim()
+      continue
+    }
+    break
+  }
+  return out
+}
+
+// Only http(s) is ever opened — the URL reaches a shell-open handler, so
+// anything else (file:, javascript:, a shell fragment) is rejected outright.
+const parseUrl = (url) => {
+  let parsed
+  try {
+    parsed = new URL(url)
+  } catch (_) {
+    return null
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return null
+  }
+  return parsed
+}
+
+const isLoopback = (hostname) => {
+  const host = (hostname || '').toLowerCase().replace(/^\[|\]$/g, '')
+  return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '0.0.0.0'
+}
+
+const urlPort = (parsed) => {
+  if (parsed.port) return Number(parsed.port)
+  return parsed.protocol === 'https:' ? 443 : 80
+}
+
+const printManually = (url) => {
+  console.log(colors.yellow(`\nCouldn't open browser automatically. Open this URL manually:\n`))
+  console.log(colors.cyan(url) + '\n')
+}
+
+// Cross-platform browser opener. Falls back to printing the URL — matters for
+// SSH / headless / broken default handlers, where `open` silently no-ops.
+// Resolves true when the opener exited cleanly, false when we fell back to
+// printing; it never rejects, so callers can't be left hanging.
+const openBrowser = (url) => new Promise((resolve) => {
+  const cleaned = stripQuotes(url)
+  const parsed = parseUrl(cleaned)
+  if (!parsed) {
+    printManually(cleaned)
+    resolve(false)
+    return
+  }
+
+  const target = parsed.toString()
+  // execFile (not exec) so the URL is passed as an argument rather than
+  // spliced into a shell command line. On Windows `start` is a cmd builtin,
+  // hence the explicit cmd.exe; the empty "" is the window title `start`
+  // would otherwise eat the URL as.
+  const [cmd, args] = process.platform === 'darwin' ? ['open', [target]]
+    : process.platform === 'win32' ? [process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', 'start', '""', `"${target}"`]]
+    : ['xdg-open', [target]]
+
+  try {
+    execFile(cmd, args, { windowsVerbatimArguments: process.platform === 'win32' }, (err) => {
+      if (err) {
+        printManually(target)
+        resolve(false)
+        return
+      }
+      resolve(true)
+    })
+  } catch (_) {
+    printManually(target)
+    resolve(false)
+  }
+})
+
+// Resolves true once something accepts a TCP connection on host:port, false
+// if the wait window elapses first. Used so we open the browser after the
+// toolserver is up instead of racing it onto a "connection refused" page.
+const waitForPort = ({ port, host = '127.0.0.1', timeout = 60000, interval = 250 }) => new Promise((resolve) => {
+  const deadline = Date.now() + timeout
+
+  const attempt = () => {
+    const socket = new net.Socket()
+    let settled = false
+
+    const done = (ok) => {
+      if (settled) return
+      settled = true
+      socket.removeAllListeners()
+      socket.destroy()
+      if (ok) {
+        resolve(true)
+        return
+      }
+      if (Date.now() >= deadline) {
+        resolve(false)
+        return
+      }
+      // Deliberately not unref'd: between probes this timer is the only
+      // thing holding the event loop open, and `deadline` already bounds it.
+      setTimeout(attempt, interval)
+    }
+
+    // Cap each probe so a black-holed connect can't outlive the deadline.
+    socket.setTimeout(Math.max(1, Math.min(interval * 4, deadline - Date.now())))
+    socket.once('connect', () => done(true))
+    socket.once('timeout', () => done(false))
+    socket.once('error', () => done(false))
+    socket.connect(port, host)
+  }
+
+  attempt()
+})
+
+// `surph browser <url>`: tolerate stray quotes, wait for a local server to
+// come up, then open. Never hangs — on timeout or failure the URL is printed.
+const openBrowserWhenReady = async (url, { timeout = 60000 } = {}) => {
+  const cleaned = stripQuotes(url)
+  const parsed = parseUrl(cleaned)
+  if (!parsed) {
+    printManually(cleaned)
+    return false
+  }
+
+  if (isLoopback(parsed.hostname)) {
+    const host = parsed.hostname === '0.0.0.0' ? '127.0.0.1' : parsed.hostname.replace(/^\[|\]$/g, '')
+    const ready = await waitForPort({ port: urlPort(parsed), host, timeout })
+    if (!ready) {
+      console.log(colors.yellow(`\nNothing is listening on ${host}:${urlPort(parsed)} after ${Math.round(timeout / 1000)}s.`))
+      printManually(parsed.toString())
+      return false
+    }
+  }
+
+  return openBrowser(parsed.toString())
+}
+
+module.exports = { openBrowser, openBrowserWhenReady, waitForPort, stripQuotes }

package/utils/command.js

@@ -0,0 +1,86 @@
+const { spawn } = require('child_process')
+
+// Keep the tail of a noisy command's output without letting a pathological
+// run (a dependency that prints megabytes) grow unbounded in memory.
+const MAX_OUTPUT = 200 * 1024
+
+// Captures stdout/stderr; calls onLine per complete line. On failure, rejects with `.output`.
+// Optional `retain(line)` filters what is kept in that tail (bounded by MAX_OUTPUT).
+const runCaptured = (command, args, { cwd, env, onLine, retain } = {}) => new Promise((resolve, reject) => {
+  // npm ships as npm.cmd on Windows, which spawn() refuses to run without a
+  // shell. The args here are fixed literals, so nothing user-supplied is
+  // handed to cmd.exe. With a shell, Node wants a single command string:
+  // passing an args array alongside `shell: true` emits DEP0190 on stderr,
+  // which tears through the live progress bar.
+  const isWindows = process.platform === 'win32'
+  const bin = isWindows && command === 'npm' ? 'npm.cmd' : command
+
+  let child
+  try {
+    const options = {
+      cwd,
+      env: env || process.env,
+      shell: isWindows,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true
+    }
+    child = isWindows
+      ? spawn([bin, ...args].join(' '), options)
+      : spawn(bin, args, options)
+  } catch (error) {
+    reject(error)
+    return
+  }
+
+  let output = ''
+  let pending = ''
+
+  const keep = (line) => {
+    if (retain && !retain(line)) return
+    output += `${line}\n`
+    if (output.length > MAX_OUTPUT) {
+      output = output.slice(output.length - MAX_OUTPUT)
+    }
+  }
+
+  const collect = (chunk) => {
+    pending += chunk.toString()
+    const lines = pending.split(/\r?\n/)
+    pending = lines.pop()
+    lines.forEach((line) => {
+      keep(line)
+      if (onLine) onLine(line)
+    })
+  }
+
+  const flush = () => {
+    if (!pending) return
+    const line = pending
+    pending = ''
+    keep(line)
+    if (onLine) onLine(line)
+  }
+
+  child.stdout.on('data', collect)
+  child.stderr.on('data', collect)
+
+  child.on('error', (error) => {
+    flush()
+    error.output = output
+    reject(error)
+  })
+
+  child.on('close', (code, signal) => {
+    flush()
+    if (code === 0) {
+      resolve(output)
+      return
+    }
+    const reason = signal ? `was killed with ${signal}` : `exited with code ${code}`
+    const error = new Error(`${command} ${args.join(' ')} ${reason}`)
+    error.output = output
+    reject(error)
+  })
+})
+
+module.exports = { runCaptured }

package/utils/progress.js

@@ -0,0 +1,226 @@
+const cliProgress = require('cli-progress')
+const colors = require('colors/safe')
+
+const BAR_SIZE = 16
+const MIN_WIDTH_FOR_BAR = 56
+
+// cli-progress redraws at ~10 fps; sub-frame steps may not paint without a minimum dwell.
+const MIN_VISIBLE_STEP_MS = 100
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+// Non-TTY output gets plain lines (no escape sequences).
+const isInteractive = (stream = process.stdout) =>
+  Boolean(stream && stream.isTTY) && process.env.TERM !== 'dumb' && !process.env.CI
+
+// Legacy conhost uses an OEM code page; WT and VS Code terminals are UTF-8.
+const supportsUnicode = () => process.platform !== 'win32'
+  || Boolean(process.env.WT_SESSION)
+  || process.env.TERM_PROGRAM === 'vscode'
+
+const GLYPHS = {
+  unicode: { tick: '✓', barDone: '█', barTodo: '░', ellipsis: '…' },
+  ascii: { tick: '+', barDone: '#', barTodo: '-', ellipsis: '...' }
+}
+
+const oneLine = (text) => String(text == null ? '' : text)
+  .replace(/[\r\n]+/g, ' ')
+  // eslint-disable-next-line no-control-regex
+  .replace(/\x1B\[[0-9;]*[A-Za-z]/g, '')
+  .replace(/[\x00-\x1F\x7F]/g, ' ')
+  .replace(/\s+/g, ' ')
+  .trim()
+
+const painter = (interactive) => (fn, text) => (interactive ? fn(text) : text)
+
+const truncate = (text, max, ellipsis) => {
+  if (max <= ellipsis.length) return ''
+  return text.length > max ? text.slice(0, max - ellipsis.length) + ellipsis : text
+}
+
+const clamp01 = (n) => (n < 0 ? 0 : n > 1 ? 1 : n)
+
+// Weighted steps: one live progress line in TTY mode; completed steps log above it.
+class StepProgress {
+  constructor(steps, options = {}) {
+    this.steps = steps.map((step) => Object.assign({ weight: 1 }, step))
+    this.stream = options.stream || process.stdout
+    this.interactive = options.interactive === undefined
+      ? isInteractive(this.stream)
+      : options.interactive
+    this.heartbeatMs = options.heartbeatMs === undefined ? 15000 : options.heartbeatMs
+    this.minStepMs = options.minStepMs === undefined ? MIN_VISIBLE_STEP_MS : options.minStepMs
+    this.paint = painter(this.interactive)
+    this.glyph = GLYPHS[supportsUnicode() ? 'unicode' : 'ascii']
+
+    this.offsets = []
+    let running = 0
+    this.steps.forEach((step) => {
+      this.offsets.push(running)
+      running += step.weight
+    })
+    this.totalWeight = running || 1
+
+    this.index = -1
+    this.fraction = 0
+    this.detailText = ''
+    this.multi = null
+    this.bar = null
+    this.stepStartedAt = 0
+    this.lastHeartbeat = 0
+  }
+
+  get step() { return this.index >= 0 ? this.steps[this.index] : null }
+
+  get width() { return Math.max(20, this.stream.columns || 80) }
+
+  get progress() {
+    if (this.index < 0) return 0
+    return clamp01((this.offsets[this.index] + this.fraction * this.step.weight) / this.totalWeight)
+  }
+
+  formatLine() {
+    const width = this.width
+    const percentage = `${Math.floor(this.progress * 100)}`.padStart(3) + '%'
+    const step = this.step
+    const elapsed = Date.now() - this.stepStartedAt
+    const age = elapsed >= 2000 ? ` (${Math.round(elapsed / 1000)}s)` : ''
+    const label = this.detailText ? `${step.doing} - ${this.detailText}` : `${step.doing}...`
+
+    const fit = (room) => truncate(
+      label.length + age.length <= room ? label + age : label,
+      room,
+      this.glyph.ellipsis
+    )
+
+    if (width < MIN_WIDTH_FOR_BAR) {
+      return `${percentage} ${fit(width - percentage.length - 2)}`
+    }
+
+    const filled = Math.min(BAR_SIZE, Math.round(this.progress * BAR_SIZE))
+    const bar = this.glyph.barDone.repeat(filled) + this.glyph.barTodo.repeat(BAR_SIZE - filled)
+    const head = `  ${bar} ${percentage}  `
+    return `  ${this.paint(colors.cyan, bar)} ${percentage}  ` + fit(width - head.length - 1)
+  }
+
+  logLine(marker, text, color) {
+    const body = truncate(text, this.width - 3 - marker.length, this.glyph.ellipsis)
+    const line = `  ${color ? this.paint(color, marker) : marker} ${body}`
+    if (this.multi) {
+      this.multi.log(`${line}\n`)
+      return
+    }
+    this.stream.write(`${line}\n`)
+  }
+
+  start() {
+    if (!this.interactive) return
+    this.multi = new cliProgress.MultiBar({
+      format: () => this.formatLine(),
+      stream: this.stream,
+      hideCursor: true,
+      clearOnComplete: true,
+      gracefulExit: true,
+      etaAsynchronousUpdate: false,
+      forceRedraw: true
+    })
+    this.bar = this.multi.create(this.totalWeight, 0)
+  }
+
+  render() {
+    if (this.bar) {
+      this.bar.update(this.progress * this.totalWeight)
+    }
+  }
+
+  begin(id) {
+    const index = this.steps.findIndex((step) => step.id === id)
+    if (index === -1) {
+      throw new Error(`unknown scaffolding step: ${id}`)
+    }
+    this.index = index
+    this.fraction = 0
+    this.detailText = ''
+    this.stepStartedAt = Date.now()
+    this.lastHeartbeat = this.stepStartedAt
+    if (this.interactive) {
+      this.render()
+      return
+    }
+    this.logLine('>', `${this.steps[index].doing}...`)
+  }
+
+  advance(fraction, detail) {
+    if (this.index < 0) return
+    this.fraction = Math.max(this.fraction, clamp01(fraction))
+    if (detail !== undefined) this.detail(detail)
+    else this.render()
+  }
+
+  detail(text) {
+    if (this.index < 0) return
+    const clean = oneLine(text)
+    if (this.interactive) {
+      this.detailText = clean
+      this.render()
+      return
+    }
+    if (this.heartbeatMs <= 0) return
+    const now = Date.now()
+    if (now - this.lastHeartbeat < this.heartbeatMs) return
+    this.lastHeartbeat = now
+    const seconds = Math.round((now - this.stepStartedAt) / 1000)
+    this.logLine(' ', `still working: ${clean || this.step.doing} (${seconds}s)`)
+  }
+
+  async done(note) {
+    if (this.index < 0) return
+    const elapsed = Date.now() - this.stepStartedAt
+    if (this.interactive && elapsed < this.minStepMs) {
+      this.advance(0.6)
+      await sleep(this.minStepMs - elapsed)
+    }
+    this.fraction = 1
+    this.detailText = ''
+    this.render()
+    const seconds = ((Date.now() - this.stepStartedAt) / 1000).toFixed(1)
+    const suffix = note ? `${note}, ${seconds}s` : `${seconds}s`
+    this.logLine(this.glyph.tick, `${this.step.done} (${suffix})`, colors.green)
+  }
+
+  warn(message) {
+    this.logLine('!', message, colors.yellow)
+  }
+
+  stop() {
+    if (this.multi) {
+      this.multi.update() // flush multi.log buffer before stop()
+      this.multi.stop()
+      this.multi = null
+      this.bar = null
+    }
+  }
+
+  async complete() {
+    if (this.index >= 0) await this.done()
+    this.index = this.steps.length - 1
+    this.fraction = 1
+    this.render()
+    this.stop()
+  }
+
+  fail(error) {
+    const step = this.step ? this.step.doing : 'startup'
+    this.stop()
+    console.log(this.paint(colors.red, `\nFAILED while ${step.charAt(0).toLowerCase()}${step.slice(1)}`))
+    console.log(`  ${error && error.message ? error.message : error}\n`)
+    const output = error && error.output ? String(error.output).trim() : ''
+    if (output) {
+      console.log(this.paint(colors.gray, '--- output ---'))
+      console.log(output)
+      console.log(this.paint(colors.gray, '--------------') + '\n')
+    }
+  }
+}
+
+module.exports = { StepProgress, isInteractive, oneLine, painter, supportsUnicode }

package/utils/windowsConsole.js

@@ -0,0 +1,130 @@
+const { spawn } = require('child_process')
+
+// --- Why this file exists -------------------------------------------------
+//
+// Windows' legacy console host (conhost, what `cmd.exe` and the Win+R "Windows
+// PowerShell" window use) ships with **QuickEdit Mode on by default**. With it
+// on, a single click anywhere in the window puts the console into selection
+// mode, and selection mode *blocks the attached process's writes to stdout*.
+// A CLI that redraws a progress line then appears frozen — which is exactly
+// what QA reported: the progress messages stop updating and never recover
+// until the user presses Esc or right-clicks.
+//
+// There is no command-line flag for this. `powershell.exe` has no switch that
+// turns QuickEdit off, and neither does `cmd.exe` or `conhost.exe` — the flag
+// QuickEdit lives behind is a *console mode bit*, ENABLE_QUICK_EDIT_MODE
+// (0x0040) on the console input buffer, and the only two supported ways to
+// clear it are:
+//
+//   1. `SetConsoleMode()` on CONIN$ at runtime — affects the console this
+//      process is attached to, takes effect immediately. This is what we do.
+//   2. HKCU\Console\QuickEdit = 0 in the registry — only applies to console
+//      windows opened *afterwards*, and permanently changes a user-global
+//      preference. Rejected: it cannot fix the window we are already running
+//      in, and silently rewriting a user's terminal defaults is not ours to do.
+//
+// Node has no binding for SetConsoleMode, so option 1 goes through PowerShell,
+// which is present on every Windows 10 and 11 install. The console input
+// buffer is a property of the *console*, not of a process, so a child process
+// that opens CONIN$ changes the mode for our window too.
+//
+// The mode is restored when we exit: the helper holds its stdin open and waits,
+// so when this process ends (cleanly, on Ctrl+C, or killed) the pipe closes and
+// the helper puts the user's QuickEdit setting back. Leaving it off would cost
+// them click-to-copy in that window for as long as it stays open.
+
+const ENABLE_QUICK_EDIT_MODE = 0x0040
+const ENABLE_EXTENDED_FLAGS = 0x0080
+
+// ENABLE_EXTENDED_FLAGS must be set in the same call for the QuickEdit bit to
+// be honoured; the remaining bits are carried over from whatever the user had.
+const SCRIPT = `
+$ErrorActionPreference = 'Stop'
+try {
+  Add-Type -TypeDefinition @"
+using System;
+using System.Runtime.InteropServices;
+public static class SurphConsole {
+  [DllImport("kernel32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
+  public static extern IntPtr CreateFileW(string name, uint access, uint share, IntPtr sec, uint disposition, uint flags, IntPtr template);
+  [DllImport("kernel32.dll", SetLastError = true)]
+  public static extern bool GetConsoleMode(IntPtr handle, out uint mode);
+  [DllImport("kernel32.dll", SetLastError = true)]
+  public static extern bool SetConsoleMode(IntPtr handle, uint mode);
+}
+"@
+} catch { exit 1 }
+
+# Decimal, not 0xC0000000: PowerShell parses a hex literal that fits in 32 bits
+# as a *signed* Int32, so 0xC0000000 arrives as -1073741824 and binding it to a
+# uint parameter throws outright. 3221225472 is GENERIC_READ | GENERIC_WRITE.
+# The 3s are FILE_SHARE_READ | FILE_SHARE_WRITE and OPEN_EXISTING.
+#
+# CONIN$ resolves to the console we inherited from the CLI, which is the point:
+# GetStdHandle would hand back the pipe our parent gave us instead.
+$handle = [SurphConsole]::CreateFileW('CONIN$', [uint32]3221225472, [uint32]3, [IntPtr]::Zero, [uint32]3, [uint32]0, [IntPtr]::Zero)
+if ($handle -eq [IntPtr]::Zero -or $handle.ToInt64() -eq -1) { exit 1 }
+
+$mode = [uint32]0
+if (-not [SurphConsole]::GetConsoleMode($handle, [ref]$mode)) { exit 1 }
+
+# Already off (the user, or their profile, turned it off) - leave it alone.
+if (($mode -band ${ENABLE_QUICK_EDIT_MODE}) -eq 0) { exit 0 }
+
+# Widened to Int64 first so the mixed UInt32/Int32 bitwise operands cannot
+# surprise us on the way back down to the uint the API wants.
+$patched = [uint32](([int64]$mode -bor ${ENABLE_EXTENDED_FLAGS}) -band (-bnot ${ENABLE_QUICK_EDIT_MODE}))
+if (-not [SurphConsole]::SetConsoleMode($handle, $patched)) { exit 1 }
+
+# Block until the CLI exits and our stdin pipe closes, then hand the user's
+# console back the way we found it.
+try { $null = [Console]::In.ReadToEnd() } catch { }
+[void][SurphConsole]::SetConsoleMode($handle, $mode)
+`
+
+// Windows Terminal and the VS Code terminal drive the console through ConPTY
+// and do their own text selection, which never stalls the writer — the
+// QuickEdit bit is inert there, so spawning PowerShell would only cost startup
+// time for nothing.
+const needsQuickEditFix = () => process.platform === 'win32'
+  && Boolean(process.stdout && process.stdout.isTTY)
+  && !process.env.WT_SESSION
+  && process.env.TERM_PROGRAM !== 'vscode'
+  && process.env.SURPH_NO_CONSOLE_FIX !== '1'
+
+// Best-effort and entirely silent: a console we could not reconfigure is a
+// slightly worse progress display, never a failed command. Returns the helper
+// process when one was started, otherwise null.
+const prepareWindowsConsole = () => {
+  if (!needsQuickEditFix()) return null
+
+  try {
+    // -EncodedCommand takes base64 UTF-16LE and sidesteps cmd.exe's quoting
+    // rules entirely, which matters because the script contains quotes, `$`
+    // and `@"` here-strings.
+    const encoded = Buffer.from(SCRIPT, 'utf16le').toString('base64')
+    const child = spawn('powershell.exe', [
+      '-NoProfile',
+      '-NonInteractive',
+      '-ExecutionPolicy', 'Bypass',
+      '-EncodedCommand', encoded
+    ], {
+      stdio: ['pipe', 'ignore', 'ignore'],
+      windowsHide: true
+    })
+
+    child.on('error', () => {})
+    if (child.stdin) child.stdin.on('error', () => {})
+
+    // Neither the process handle nor the stdin pipe should keep the CLI alive;
+    // the helper's whole job is to outlive nothing.
+    child.unref()
+    if (child.stdin && child.stdin.unref) child.stdin.unref()
+
+    return child
+  } catch (_) {
+    return null
+  }
+}
+
+module.exports = { prepareWindowsConsole, needsQuickEditFix }