[bug] BudJS CLI crashes with "The URL must be of scheme file" error when packages resolve to non-file:// URLs

[broskees]

Agreement

• This is not a duplicate of an existing issue
• I have read the guidelines for Contributing to Roots Projects
• This is not a personal support request that should be posted on the Roots Discourse community

Describe the issue

Bud fails on bud build and bud dev with the error "The URL must be of scheme file" when scanning project dependencies for potential BudJS plugins. This occurs because the CLI Finder attempts to call fileURLToPath() on URLs that are not file:// scheme (e.g., https:// URLs from packages with external/browser exports).

Expected Behavior

BudJS should gracefully handle packages that resolve to non-file:// URLs and skip them when searching for plugin commands, allowing the build/dev process to continue normally.

Actual Behavior

BudJS crashes immediately with:

BudError
✘ The URL must be of scheme file

ℹ Stack trace
 at ./node_modules/ink/build/components/Static.js:24:16
 at Array.map (<anonymous>)
 at Static (./node_modules/ink/build/components/Static.js:23:36)

I stepped through it with the node debugger and put some logging and found that the actual error originates from:

TypeError [ERR_INVALID_URL_SCHEME]: The URL must be of scheme file
    at fileURLToPath (node:internal/url:1509:11)
    at file:///[project]/node_modules/@roots/bud/lib/cli/finder/index.js:134:63

Root Cause:
In @roots/bud/lib/cli/finder/index.js, the resolve() method calls import.meta.resolve() on all project dependencies to find potential BudJS plugins. Some packages resolve to non-file:// URLs (e.g., packages with browser-specific exports or external dependencies), and the code attempts to call fileURLToPath() on ALL resolved paths without checking their URL scheme first.

Proposed Fix:
Filter out non-file:// URLs before calling fileURLToPath():

--- a/node_modules/@roots/bud/lib/cli/finder/index.js
+++ b/node_modules/@roots/bud/lib/cli/finder/index.js
@@ -131,7 +131,7 @@ export class Finder {
             }
             catch (error) { }
         }))
-            .then(paths => paths.filter(isString).map(path => fileURLToPath(path)))
+            .then(paths => paths.filter(isString).filter(path => path.startsWith('file://')).map(path => fileURLToPath(path)))
             .then(async (paths) => await Promise.all(paths.map(async (path) => {
             try {
                 const exists = await fs.exists(path);

Workaround:
Users can apply this fix using patch-package until an official fix is released. The patch is minimal and only adds a filter to check for file:// URLs before attempting to convert them to file paths.

Steps To Reproduce

1. Install BudJS 6.24.0 in a project with various npm dependencies
2. Run yarn bud build or yarn bud dev
3. The CLI will crash during initialization when it tries to scan dependencies

It may not reproduce in all projects, as it depends on having packages in your dependency tree that resolve to non-file:// URLs when using import.meta.resolve().

version

6.24.0

Logs

Error type: object
Error name: TypeError
Error message: The URL must be of scheme file
Error constructor: TypeError
Error keys: [ 'code' ]
Error JSON: {
  "stack": "TypeError [ERR_INVALID_URL_SCHEME]: The URL must be of scheme file\n    at fileURLToPath (node:internal/url:1509:11)\n    at file:///Users/[user]/project/node_modules/@roots/bud/lib/cli/finder/index.js:134:63\n    at Array.map (<anonymous>)\n    at file:///Users/[user]/project/node_modules/@roots/bud/lib/cli/finder/index.js:134:51\n    at async Finder.resolve (file:///Users/[user]/project/node_modules/@roots/bud/lib/cli/finder/index.js:128:16)\n    at async Finder.getModules (file:///Users/[user]/project/node_modules/@roots/bud/lib/cli/finder/index.js:64:22)\n    at async registerFoundCommands (file:///Users/[user]/project/node_modules/@roots/bud/lib/cli/app/index.js:84:9)",
  "code": "ERR_INVALID_URL_SCHEME",
  "message": "The URL must be of scheme file"
}

Configuration

Node.js: v22.12.0
Package manager: yarn v1.22.22

Relevant .budfiles