refactor: migrate from qqjs to execa with custom wrapper (#3678)

* refactor: migrate from qqjs to execa with custom wrapper

Replaces qqjs dependency with execa v9 and introduces a lightweight
exec.ts wrapper that preserves qqjs behavior (stdio inheritance,
command logging, error handling).

Changes:
- Created scripts/utils/exec.ts wrapper with x(), shell(), stdout(), and run() helpers
- Migrated all qqjs usage to exec.ts (install-scripts.js, version.js, smoke tests)
- Fixed execa v8→v9 breaking changes in homebrew.js and plugin tests
  - Updated import syntax: import execa from 'execa' → import {execa} from 'execa'
  - Replaced execa.command() with shell() helper (removed in v9)
  - Updated stdio array syntax to named properties
- Removed qqjs dependency (63 packages removed)

The exec.ts wrapper provides a consistent API across all scripts:
- x(cmd, args, opts): Execute with args array (stdio: 'inherit' default)
- shell(cmd, opts): Execute shell commands (strings with pipes, etc.)
- stdout(cmd, args, opts): Capture stdout as string (trims trailing newline)
- run(fn): Async error handler (logs errors, sets process.exitCode)
- config.silent: Toggle command logging

All existing functionality preserved, no behavior changes.

* chore: reorder properties in exec.ts for consistency

* refactor: simplify and rename exec.ts to script-exec.ts

Simplifications:
- Removed unused config.silent feature (only ever set to false)
- Inlined console.log calls (removed log() helper)
- Removed intermediate defaultOptions variables
- Reduced from 75 lines to 60 lines (20% reduction)

Renamed exec.ts → script-exec.ts to clarify purpose:
- script-exec.ts provides wrappers for shell scripts (stdio: 'inherit')
- Tests that need to capture output use execa directly

Changes:
- scripts/utils/exec.ts → scripts/utils/script-exec.ts
- Updated all imports across 5 files
- smoke.acceptance.test.ts: uses execa directly (needs output capture)
- plugin.acceptance.test.ts: uses script-exec.ts (no capture needed)
- Fixed TypeScript syntax in install-scripts.js (removed 'as const')

All tests pass with proper type checking.

* refactor: convert script-exec to plain JavaScript

Converted script-exec from TypeScript to plain JavaScript to eliminate
the build step dependency. Scripts can now run directly without requiring
'npm run build' first, which is more reliable for CI/CD pipelines.

Changes:
- src/lib/scripts/script-exec.ts → scripts/utils/script-exec.js
- Removed all TypeScript type annotations
- Reverted all imports back to ../utils/script-exec.js paths
- No build step required

Benefits:
- Scripts work immediately without compilation
- Simpler CI/CD - no build step before running scripts
- Fewer failure points in release automation
- 60 lines of clean, dependency-minimal JavaScript

Validation:
- All scripts pass syntax check
- install-scripts.js executes correctly
- version.js executes and returns version
- All tests type check correctly

* fix linting

Author: eablack

package-lock.json

@@ -45,7 +45,7 @@
     "date-fns": "^2.30.0",
     "debug": "^4.4.3",
     "eventsource": "^4",
-    "execa": "5.1.1",
+    "execa": "^9.6.1",
     "filesize": "^10.1",
     "foreman": "^3.0.1",
     "fs-extra": "^11.3.0",
@@ -130,7 +130,6 @@
     "mock-stdin": "^1",
     "nock": "^14.0.12",
     "oclif": "^4.22.87",
-    "qqjs": "0.3.11",
     "rimraf": "5.0.5",
     "sinon": "^21.0.2",
     "source-map-support": "^0.5.21",

package.json

@@ -1,12 +1,11 @@
 #!/usr/bin/env node
 
-import execa from 'execa'
 import path from 'node:path'
 import {fileURLToPath} from 'node:url'
-import qq from 'qqjs'
 
 import getHerokuS3Bucket from '../utils/get-heroku-s3-bucket.js'
 import isStableRelease from '../utils/is-stable-release.js'
+import {run, shell} from '../utils/script-exec.js'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
@@ -16,25 +15,17 @@ const opts = {
   stdio: 'inherit',
 }
 
-qq.config.silent = false
+await run(async () => {
+  const {GITHUB_REF_NAME, GITHUB_REF_TYPE} = process.env
 
-try {
-  await qq.run(async () => {
-    const {GITHUB_REF_NAME, GITHUB_REF_TYPE} = process.env
-
-    if (isStableRelease(GITHUB_REF_TYPE, GITHUB_REF_NAME)) {
-      const HEROKU_S3_BUCKET = await getHerokuS3Bucket()
-      await execa.command(`aws s3 cp --content-type text/plain --cache-control max-age=604800 ./install-standalone.sh s3://${HEROKU_S3_BUCKET}/install-standalone.sh`, opts)
-      await execa.command(`aws s3 cp --content-type text/plain --cache-control max-age=604800 ./install-standalone.sh s3://${HEROKU_S3_BUCKET}/install.sh`, opts)
-      await execa.command(`aws s3 cp --content-type text/plain --cache-control max-age=604800 ./install-ubuntu.sh s3://${HEROKU_S3_BUCKET}/install-ubuntu.sh`, opts)
-    } else {
-      console.log('Not on stable release, skipping updating install scripts')
-      // eslint-disable-next-line n/no-process-exit
-      process.exit(0)
-    }
-  })
-} catch (error) {
-  console.error(error)
-  // eslint-disable-next-line n/no-process-exit
-  process.exit(1)
-}
+  if (isStableRelease(GITHUB_REF_TYPE, GITHUB_REF_NAME)) {
+    const HEROKU_S3_BUCKET = await getHerokuS3Bucket()
+    await shell(`aws s3 cp --content-type text/plain --cache-control max-age=604800 ./install-standalone.sh s3://${HEROKU_S3_BUCKET}/install-standalone.sh`, opts)
+    await shell(`aws s3 cp --content-type text/plain --cache-control max-age=604800 ./install-standalone.sh s3://${HEROKU_S3_BUCKET}/install.sh`, opts)
+    await shell(`aws s3 cp --content-type text/plain --cache-control max-age=604800 ./install-ubuntu.sh s3://${HEROKU_S3_BUCKET}/install-ubuntu.sh`, opts)
+  } else {
+    console.log('Not on stable release, skipping updating install scripts')
+    // eslint-disable-next-line n/no-process-exit
+    process.exit(0)
+  }
+})

scripts/postrelease/install-scripts.js

@@ -1,4 +1,3 @@
-import execa from 'execa'
 import crypto from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
@@ -9,6 +8,7 @@ import {rimrafSync} from 'rimraf'
 
 import getHerokuS3Bucket from '../utils/get-heroku-s3-bucket.js'
 import isStableRelease from '../utils/is-stable-release.js'
+import {run, shell, x} from '../utils/script-exec.js'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
@@ -41,7 +41,7 @@ const ARCH_ARM = 'arm64'
 function downloadFileFromS3(s3Path, fileName, downloadPath) {
   const downloadTo = path.join(downloadPath, fileName)
   const commandStr = `aws s3 cp s3://${HEROKU_S3_BUCKET}/${s3Path}/${fileName} ${downloadTo}`
-  return execa.command(commandStr)
+  return shell(commandStr)
 }
 
 async function updateHerokuFormula(brewDir) {
@@ -94,7 +94,7 @@ async function updateHerokuFormula(brewDir) {
 
 async function setupGit() {
   const githubSetupPath = path.join(__dirname, '..', 'utils', '_github_setup')
-  await execa(githubSetupPath)
+  await x(githubSetupPath, [])
 }
 
 async function updateHomebrew() {
@@ -108,7 +108,7 @@ async function updateHomebrew() {
   await setupGit()
 
   console.log(`cloning https://github.com/heroku/homebrew-brew to ${homebrewDir}`)
-  await execa(
+  await x(
     'git',
     [
       'clone',
@@ -122,7 +122,7 @@ async function updateHomebrew() {
 
   // run in git in cloned heroku/homebrew-brew git directory
   const git = async (args, opts = {}) => {
-    await execa('git', ['-C', homebrewDir, ...args], opts)
+    await x('git', ['-C', homebrewDir, ...args], opts)
   }
 
   console.log('updating local git...')
@@ -135,10 +135,6 @@ async function updateHomebrew() {
   }
 }
 
-try {
+await run(async () => {
   await updateHomebrew()
-} catch (error) {
-  console.error('error running scripts/release/homebrew.js', error)
-  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit
-  process.exit(1)
-}
+})

scripts/release/homebrew.js

@@ -0,0 +1,60 @@
+import {execa} from 'execa'
+
+/**
+ * Execute a command with args array
+ * Logs the command and uses stdio: 'inherit' by default
+ */
+export function x(command, args, options) {
+  console.log(`$ ${command} ${args.join(' ')}`)
+  return execa(command, args, {
+    stdio: 'inherit',
+    ...options,
+  })
+}
+
+/**
+ * Execute a shell command (string with interpolation, pipes, etc.)
+ * Logs the command and uses stdio: 'inherit' by default
+ */
+export function shell(command, options) {
+  console.log(`$ ${command}`)
+  return execa(command, {
+    shell: true,
+    stdio: 'inherit',
+    ...options,
+  })
+}
+
+/**
+ * Execute a command and return stdout as string
+ * Trims trailing newline
+ */
+export async function stdout(command, args, options) {
+  console.log(`$ ${command} ${args.join(' ')}`)
+  const result = await execa(command, args, {
+    ...options,
+    stderr: 'inherit',
+    stdin: 'inherit',
+    stdout: 'pipe',
+  })
+  const output = typeof result.stdout === 'string' ? result.stdout : ''
+  return output.replace(/\n$/, '')
+}
+
+/**
+ * Run an async function with error handling
+ * Catches errors, logs them, and sets process.exitCode
+ */
+export async function run(fn) {
+  try {
+    return await fn()
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(error.stack || error.message)
+    } else {
+      console.error(error)
+    }
+
+    process.exitCode = 1
+  }
+}

scripts/utils/script-exec.js

@@ -1,7 +1,8 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import {fileURLToPath} from 'node:url'
-import qq from 'qqjs'
+
+import {stdout} from './script-exec.js'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
@@ -11,7 +12,7 @@ export default async function getVersion() {
   let {version} = packageJson
   if (version.includes('-')) {
     const channel = version.split('-')[1].split('.')[0]
-    const sha = await qq.x.stdout('git', ['rev-parse', '--short', 'HEAD'])
+    const sha = await stdout('git', ['rev-parse', '--short', 'HEAD'])
     version = `${version.split('-')[0]}-${channel}.${sha}`
   }
 

scripts/utils/version.js

@@ -1,8 +1,9 @@
-import execa from 'execa'
 import fs from 'fs-extra'
 import path from 'node:path'
 import {fileURLToPath} from 'node:url'
 
+import {x} from '../../scripts/utils/script-exec.js'
+
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
 const plugins = ['@heroku-cli/plugin-applink']
@@ -64,11 +65,13 @@ describe('plugins', function () {
         cloneUrl = repoUrl
       }
 
-      await execa('git', ['clone', cloneUrl, cwd])
-      const opts = {cwd, stdio: [0, 1, 2]}
-      await execa('git', ['checkout', `v${pkg.version}`], opts)
-      await execa('npm', [], opts)
-      await execa('npm', ['test'], opts)
+      await x('git', ['clone', cloneUrl, cwd])
+      const opts = {
+        cwd, stderr: 'inherit', stdin: 'inherit', stdout: 'inherit',
+      } as const
+      await x('git', ['checkout', `v${pkg.version}`], opts)
+      await x('npm', [], opts)
+      await x('npm', ['test'], opts)
     })
   }
 })

test/acceptance/plugin.acceptance.test.ts

@@ -1,10 +1,10 @@
 // tslint:disable no-console
 import ansis from 'ansis'
 import {expect} from 'chai'
+import {execa} from 'execa'
 import fs from 'fs-extra'
 import path from 'node:path'
 import {fileURLToPath} from 'node:url'
-import * as qq from 'qqjs'
 
 import normalizeTableOutput from '../helpers/utils/normalize-table-output.js'
 import commandsOutput from './commands-output.js'
@@ -16,7 +16,8 @@ const bin = path.join(__dirname, '../../bin/run')
 
 function run(args = '') {
   console.log(`$ heroku ${args}`)
-  return qq.x([bin, args].join(' '), {stdio: undefined})
+  // Use execa directly to capture output for test assertions
+  return execa([bin, args].join(' '), {shell: true})
 }
 
 // Smoke tests expect the CI account: heroku-cli@salesforce.com, app heroku-cli-ci-smoke-test-app,