feat: friendlier error message when command not found

.changeset/chatty-houses-build.md

@@ -0,0 +1,6 @@
+---
+"@pnpm/plugin-commands-script-runners": patch
+"pnpm": patch
+---
+
+Make the error message when user attempting to run a command that does not exist friendlier

exec/plugin-commands-script-runners/src/buildCommandNotFoundHint.ts

@@ -1,12 +1,46 @@
 import { type PackageScripts } from '@pnpm/types'
 import didYouMean, { ReturnTypeEnums } from 'didyoumean2'
+import { readdir } from 'fs/promises'
+import path from 'path'
+
+export function getNearest (name: string, list?: readonly string[]) {
+  return list && didYouMean(name, list ?? [], {
+    returnType: ReturnTypeEnums.FIRST_CLOSEST_MATCH,
+  })
+}
+
+export async function getNearestProgram (opts: {
+  programName: string,
+  dir: string,
+  workspaceDir: string | undefined,
+}) {
+  try {
+    const { programName, dir, workspaceDir } = opts
+    const binDir = path.join(dir, 'node_modules', '.bin')
+    const programListPromise = readdir(binDir) // await is omitted to take advantage of concurrency
+    let programList!: string[]
+    if (workspaceDir && workspaceDir !== dir) {
+      const workspaceBinDir = path.join(workspaceDir, 'node_modules', '.bin')
+      const programListExtension = await readdir(workspaceBinDir)
+      programList = await programListPromise
+      programList.push(...programListExtension)
+    } else {
+      programList = await programListPromise
+    }
+    return getNearest(programName, await programListPromise)
+  } catch (_err) {
+    return null
+  }
+}
+
+export function getNearestScript (scriptName: string, scripts?: PackageScripts | undefined) {
+  return getNearest(scriptName, scripts && Object.keys(scripts))
+}
 
 export function buildCommandNotFoundHint (scriptName: string, scripts?: PackageScripts | undefined) {
   let hint = `Command "${scriptName}" not found.`
 
-  const nearestCommand = scripts && didYouMean(scriptName, Object.keys(scripts), {
-    returnType: ReturnTypeEnums.FIRST_CLOSEST_MATCH,
-  })
+  const nearestCommand = getNearestScript(scriptName, scripts)
 
   if (nearestCommand) {
     hint += ` Did you mean "pnpm run ${nearestCommand}"?`

exec/plugin-commands-script-runners/src/exec.ts

@@ -21,7 +21,7 @@ import {
 import { PnpmError } from '@pnpm/error'
 import which from 'which'
 import writeJsonFile from 'write-json-file'
-import { buildCommandNotFoundHint } from './buildCommandNotFoundHint'
+import { getNearestProgram, getNearestScript } from './buildCommandNotFoundHint'
 
 export const shorthands = {
   parallel: runShorthands.parallel,
@@ -133,6 +133,7 @@ export async function handler (
     shellMode?: boolean
     resumeFrom?: string
     reportSummary?: boolean
+    implicitlyFellbackFromRun?: boolean
   } & Pick<Config, 'extraBinPaths' | 'extraEnv' | 'lockfileDir' | 'dir' | 'userAgent' | 'recursive' | 'workspaceDir'>,
   params: string[]
 ) {
@@ -212,7 +213,34 @@ export async function handler (
           result[prefix].duration = getExecutionDuration(startTime)
         } catch (err: any) { // eslint-disable-line
           if (await isErrorCommandNotFound(params[0], err)) {
-            err.hint = buildCommandNotFoundHint(params[0], (await readProjectManifestOnly(opts.dir)).scripts)
+            err.message = `Command "${params[0]}" not found`
+            if (opts.implicitlyFellbackFromRun) {
+              let nearestScript: string | null | undefined
+              try {
+                nearestScript = getNearestScript(params[0], (await readProjectManifestOnly(opts.dir)).scripts)
+              } catch (_err) {}
+              if (nearestScript) {
+                err.hint = `Did you mean "pnpm ${nearestScript}"?`
+              } else {
+                const nearestProgram = await getNearestProgram({
+                  programName: params[0],
+                  dir: opts.dir,
+                  workspaceDir: opts.workspaceDir,
+                })
+                if (nearestProgram) {
+                  err.hint = `Did you mean "pnpm ${nearestProgram}"?`
+                }
+              }
+            } else {
+              const nearestProgram = await getNearestProgram({
+                programName: params[0],
+                dir: opts.dir,
+                workspaceDir: opts.workspaceDir,
+              })
+              if (nearestProgram) {
+                err.hint = `Did you mean "pnpm exec ${nearestProgram}"?`
+              }
+            }
           } else if (!opts.recursive && typeof err.exitCode === 'number') {
             exitCode = err.exitCode
             return

exec/plugin-commands-script-runners/src/run.ts

@@ -186,6 +186,7 @@ export async function handler (
       if (opts.argv == null) throw new Error('Could not fallback because opts.argv.original was not passed to the script runner')
       return exec({
         selectedProjectsGraph: {},
+        implicitlyFellbackFromRun: true,
         ...opts,
       }, opts.argv.original.slice(1))
     }

exec/plugin-commands-script-runners/test/exec.e2e.ts

@@ -812,25 +812,86 @@ test('pnpm recursive exec report summary with --bail', async () => {
   expect(executionStatus[path.resolve('project-4')].status).toBe('queued')
 })
 
-test('pnpm exec command not found', async () => {
+test('pnpm exec command not found (implicit fallback)', async () => {
   prepare({
     scripts: {
       build: 'echo hello',
     },
   })
 
   const { selectedProjectsGraph } = await readProjects(process.cwd(), [])
-  let error!: Error & { hint: string }
+  let error!: Error & { hint?: string }
   try {
     await exec.handler({
       ...DEFAULT_OPTS,
       dir: process.cwd(),
       recursive: false,
       bail: true,
       selectedProjectsGraph,
+      implicitlyFellbackFromRun: true,
     }, ['buil'])
   } catch (err: any) { // eslint-disable-line
     error = err
   }
-  expect(error?.hint).toBe('Command "buil" not found. Did you mean "pnpm run build"?')
+  expect(error?.message).toBe('Command "buil" not found')
+  expect(error?.hint).toBe('Did you mean "pnpm build"?')
+})
+
+test('pnpm exec command not found (explicit call, without near name packages)', async () => {
+  prepare({
+    scripts: {
+      cwsay: 'echo hello',
+    },
+  })
+
+  const { selectedProjectsGraph } = await readProjects(process.cwd(), [])
+  let error!: Error & { hint?: string }
+  try {
+    await exec.handler({
+      ...DEFAULT_OPTS,
+      dir: process.cwd(),
+      recursive: false,
+      bail: true,
+      selectedProjectsGraph,
+      implicitlyFellbackFromRun: false,
+    }, ['cwsay'])
+  } catch (err: any) { // eslint-disable-line
+    error = err
+  }
+  expect(error?.message).toBe('Command "cwsay" not found')
+  expect(error?.hint).toBeFalsy()
+})
+
+test('pnpm exec command not found (explicit call, with a near name package)', async () => {
+  prepare({
+    dependencies: {
+      cowsay: '1.5.0',
+    },
+  })
+
+  const { selectedProjectsGraph } = await readProjects(process.cwd(), [])
+
+  await execa(pnpmBin, [
+    'install',
+    '--registry',
+    REGISTRY_URL,
+    '--store-dir',
+    path.resolve(DEFAULT_OPTS.storeDir),
+  ])
+
+  let error!: Error & { hint?: string }
+  try {
+    await exec.handler({
+      ...DEFAULT_OPTS,
+      dir: process.cwd(),
+      recursive: false,
+      bail: true,
+      selectedProjectsGraph,
+      implicitlyFellbackFromRun: false,
+    }, ['cwsay'])
+  } catch (err: any) { // eslint-disable-line
+    error = err
+  }
+  expect(error?.message).toBe('Command "cwsay" not found')
+  expect(error?.hint).toBe('Did you mean "pnpm exec cowsay"?')
 })