✨ improve(patch): --use flag (#2403)

- Invalidate command cache when `--use`, `--force`, `--no-cache` is used
- Ensure extensions are utilized by CLI and framework when specified with `--use`.

## Type of change

**PATCH: backwards compatible change**

sources/@roots/bud-support/src/utilities/args.ts

@@ -1,14 +1,17 @@
+import isString from '@roots/bud-support/lodash/isString'
 import minimist from 'minimist'
 
-let raw = process.argv.slice(2)
-let args = minimist(raw, {
+const raw = process.argv.slice(2)
+
+const args = minimist(raw, {
   alias: {
     '@dist': [`dist`],
     '@src': [`src`],
     '@storage': [`storage`],
     [`path.basedir`]: [`basedir`],
     [`path.dist`]: [`dist`],
     [`path.src`]: [`src`],
+    [`split-chunks`]: [`splitChunks`],
     cwd: [`basedir`],
     discovery: [`discover`],
     flush: [`force`],
@@ -21,5 +24,9 @@ let args = minimist(raw, {
   },
 })
 
+if (args.use && isString(args.use)) {
+  args.use = [args.use]
+}
+
 export default args
 export {raw}

sources/@roots/bud/src/cli/app.tsx

@@ -86,7 +86,7 @@ const registerFoundCommands = async (force: boolean = forceFlag) => {
     const finder = new Finder(context, application)
     if (!force) await finder.init()
     else {
-      await finder.findRegistrationModules()
+      await finder.getModules()
       await finder.cacheWrite()
     }
 

sources/@roots/bud/src/cli/commands/build/development/index.tsx

@@ -37,7 +37,7 @@ export default class BuildDevelopmentCommand extends BuildCommand {
     ],
   })
 
-  public override browser = browser
+  public browser = browser
 
   public hot = hot
 

sources/@roots/bud/src/cli/commands/build/index.tsx

@@ -1,6 +1,5 @@
 import isBoolean from '@roots/bud-support/lodash/isBoolean'
 import BudCommand from '@roots/bud/cli/commands'
-import cache from '@roots/bud/cli/flags/cache'
 import ci from '@roots/bud/cli/flags/ci'
 import clean from '@roots/bud/cli/flags/clean'
 import dashboard from '@roots/bud/cli/flags/dashboard'
@@ -14,7 +13,6 @@ import dry from '@roots/bud/cli/flags/dry'
 import editor from '@roots/bud/cli/flags/editor'
 import entrypointsHtml from '@roots/bud/cli/flags/entrypoints.html'
 import esm from '@roots/bud/cli/flags/esm'
-import force from '@roots/bud/cli/flags/force'
 import hash from '@roots/bud/cli/flags/hash'
 import html from '@roots/bud/cli/flags/html'
 import immutable from '@roots/bud/cli/flags/immutable'
@@ -27,7 +25,6 @@ import runtime from '@roots/bud/cli/flags/runtime'
 import silent from '@roots/bud/cli/flags/silent'
 import splitChunks from '@roots/bud/cli/flags/splitChunks'
 import storage from '@roots/bud/cli/flags/storage'
-import use from '@roots/bud/cli/flags/use'
 import verbose from '@roots/bud/cli/flags/verbose'
 
 /**
@@ -54,8 +51,6 @@ export default class BudBuildCommand extends BudCommand {
     `,
   })
 
-  public [`cache`] = cache
-
   public [`dashboard.assets`] = dashboardAssets
 
   public [`dashboard.compact`] = dashboardCompact
@@ -82,8 +77,6 @@ export default class BudBuildCommand extends BudCommand {
 
   public esm = esm
 
-  public force = force
-
   public hash = hash
 
   public html = html
@@ -108,8 +101,6 @@ export default class BudBuildCommand extends BudCommand {
 
   public override storage = storage
 
-  public use = use
-
   public override verbose = verbose
 
   /**

sources/@roots/bud/src/cli/commands/index.tsx

@@ -1,7 +1,6 @@
 import type {Context} from '@roots/bud-framework/context'
 import type {BaseContext} from '@roots/bud-support/clipanion'
 import type {ExecaReturnValue} from '@roots/bud-support/execa'
-import type browser from '@roots/bud/cli/flags/browser'
 
 import {join, parse} from 'node:path'
 import {env, exit} from 'node:process'
@@ -17,15 +16,18 @@ import isNumber from '@roots/bud-support/lodash/isNumber'
 import logger from '@roots/bud-support/logger'
 import args from '@roots/bud-support/utilities/args'
 import basedir from '@roots/bud/cli/flags/basedir'
+import cache from '@roots/bud/cli/flags/cache'
 import color from '@roots/bud/cli/flags/color'
 import debug from '@roots/bud/cli/flags/debug'
 import dry from '@roots/bud/cli/flags/dry'
 import filter from '@roots/bud/cli/flags/filter'
+import force from '@roots/bud/cli/flags/force'
 import log from '@roots/bud/cli/flags/log'
 import mode from '@roots/bud/cli/flags/mode'
 import notify from '@roots/bud/cli/flags/notify'
 import silent from '@roots/bud/cli/flags/silent'
 import storage from '@roots/bud/cli/flags/storage'
+import use from '@roots/bud/cli/flags/use'
 import verbose from '@roots/bud/cli/flags/verbose'
 import {isset} from '@roots/bud/cli/helpers/isset'
 import * as instance from '@roots/bud/instance'
@@ -78,17 +80,19 @@ export default class BudCommand extends Command<BaseContext & Context> {
 
   public basedir = basedir
 
-  public declare browser?: typeof browser
-
   public declare bud?: Bud | undefined
 
-  public color: typeof color = color
+  public cache = cache
+
+  public color = color
 
-  public debug: typeof debug = debug
+  public debug = debug
 
   public dry = dry(true)
 
-  public filter: typeof filter = filter
+  public filter = filter
+
+  public force = force
 
   public log = log
 
@@ -100,6 +104,8 @@ export default class BudCommand extends Command<BaseContext & Context> {
 
   public storage = storage
 
+  public use = use
+
   public verbose: typeof verbose = false
 
   /**
@@ -141,8 +147,7 @@ export default class BudCommand extends Command<BaseContext & Context> {
       .on(`disconnect`, bail)
       .on(`close`, bail)
 
-    const result = await process
-    return result
+    return await process
   }
 
   /**

sources/@roots/bud/src/cli/finder.ts

@@ -1,11 +1,10 @@
-/* eslint-disable no-console */
 import type {Context} from '@roots/bud-framework/context'
 
 import {dirname, join} from 'node:path/posix'
 import {fileURLToPath} from 'node:url'
 
 import {bind} from '@roots/bud-support/decorators/bind'
-import {filesystem} from '@roots/bud-support/filesystem'
+import {filesystem as fs} from '@roots/bud-support/filesystem'
 import {resolve} from '@roots/bud-support/import-meta-resolve'
 import isString from '@roots/bud-support/lodash/isString'
 
@@ -15,8 +14,9 @@ import type {Cli} from './app.js'
  * Command finder class
  */
 export class Finder {
-  public static instance: Finder
-  public fs: typeof filesystem = filesystem
+  /**
+   * Command paths
+   */
   public paths: Array<string>
 
   /**
@@ -28,64 +28,84 @@ export class Finder {
   ) {}
 
   /**
-   * Clear command cache
+   * Is cacheable
+   */
+  public get cacheable(): boolean {
+    return (
+      !this.context.use &&
+      this.context.cache !== false &&
+      this.context.force !== true
+    )
+  }
+
+  /**
+   * Clear cache
    */
   @bind
   public async cacheClear() {
     try {
-      if (await this.fs.exists(this.cachePath))
-        await this.fs.remove(this.cachePath)
+      if (await fs.exists(this.cachePath)) await fs.remove(this.cachePath)
     } catch (error) {}
   }
 
   /**
-   * Command cache path
+   * Cache path
    */
   public get cachePath() {
     return join(this.context.paths.storage, `bud.commands.yml`)
   }
 
   /**
-   * Write command cache
+   * Read cache
    */
   @bind
-  public async cacheWrite() {
-    if (this.paths) await this.fs.write(this.cachePath, this.paths)
+  public async cacheRead() {
+    return await fs.read(this.cachePath)
   }
 
   /**
-   * Find commands shipped with a given extension
+   * Write cache
    */
   @bind
-  public findExtensionCommandPaths(paths: Array<string>) {
-    return paths
-      .map(dirname)
-      .map(path => join(path, join(`bud`, `commands`, `index.js`)))
+  public async cacheWrite() {
+    if (this.paths && this.cacheable)
+      await fs.write(this.cachePath, this.paths)
   }
 
   /**
    * Get registration module paths
    */
   @bind
-  public async findRegistrationModules(): Promise<Array<any>> {
-    this.paths = await this.resolveExtensionCommandPaths(
-      this.getProjectDependencySignifiers(),
-    )
-      .then(this.findExtensionCommandPaths)
-      .then(this.resolveExtensionCommandPaths)
+  public async getModules(): Promise<Array<any>> {
+    this.paths = await this.resolve(this.getSignifiers())
+      .then(this.getPaths)
+      .then(this.resolve)
 
     return this.paths
   }
 
   /**
-   * Get array of project dependency and devDependency signifiers
+   * Get paths
    */
   @bind
-  public getProjectDependencySignifiers(): Array<string> {
-    return Object.keys({
-      ...(this.context.manifest?.dependencies ?? {}),
-      ...(this.context.manifest?.devDependencies ?? {}),
-    }).filter(signifier => !signifier.startsWith(`@types`))
+  public getPaths(paths: Array<string>) {
+    return paths
+      .map(dirname)
+      .map(path => join(path, join(`bud`, `commands`, `index.js`)))
+  }
+
+  /**
+   * Get array of project dependencies
+   */
+  @bind
+  public getSignifiers(): Array<string> {
+    return [
+      ...Object.keys({
+        ...(this.context.manifest?.dependencies ?? {}),
+        ...(this.context.manifest?.devDependencies ?? {}),
+      }),
+      ...(this.context.use ?? []),
+    ].filter(signifier => !signifier.startsWith(`@types`))
   }
 
   /**
@@ -118,24 +138,26 @@ export class Finder {
   public async init() {
     const path = join(this.context.paths.storage, `bud.commands.yml`)
     try {
-      if (await this.fs.exists(path)) {
-        this.paths = await this.fs.read(path)
+      if (
+        (await fs.exists(path)) &&
+        this.cacheable
+      ) {
+        this.paths = await fs.read(path)
         if (Array.isArray(this.paths)) return this
-        else throw new Error(`Invalid command cache.`)
+        else throw new Error()
       }
     } catch (error) {}
 
-    await this.findRegistrationModules()
-    await this.fs.write(path, this.paths)
+    await this.getModules()
+    await this.cacheWrite()
     return this
   }
 
-  @bind public async readCache() {
-    return await this.fs.read(this.cachePath)
-  }
-
+  /**
+   * Resolve signifiers against import.meta.url
+   */
   @bind
-  public async resolveExtensionCommandPaths(paths: Array<string>) {
+  public async resolve(paths: Array<string>) {
     return await Promise.all(
       paths.map(async path => {
         try {
@@ -149,7 +171,7 @@ export class Finder {
           await Promise.all(
             paths.map(async path => {
               try {
-                const exists = await this.fs.exists(path)
+                const exists = await fs.exists(path)
                 if (exists) return path
               } catch (error) {}
             }),

sources/@roots/bud/src/cli/flags/splitChunks.ts

@@ -1,5 +1,5 @@
 import {Option} from '@roots/bud-support/clipanion'
 
-export default Option.Boolean(`--splitChunks,--vendor`, undefined, {
+export default Option.Boolean(`--splitChunks,--split-chunks,--vendor`, undefined, {
   description: `Separate vendor bundle`,
 })

sources/@roots/bud/src/context/extensions.ts

@@ -46,7 +46,8 @@ const extensions: Extensions = {
 
 export default (
   manifest?: Context[`manifest`],
-  options?: Array<string>,
+  flagged: Array<string> = [],
+  options: Array<string> = [],
 ) => {
   if (!manifest || args.discovery === false)
     return withOptions(extensions, options)
@@ -79,6 +80,8 @@ export default (
       extensions.discovered.push(signifier),
     )
 
+  ;(flagged ?? []).forEach(signifier => extensions.discovered.push(signifier))
+
   return withOptions(extensions, options)
 }
 
@@ -88,6 +91,6 @@ const withOptions = (
 ) => {
   return {
     ...extensions,
-    discovered: options ?? extensions.discovered,
+    discovered: [...extensions.discovered, ...options],
   }
 }

sources/@roots/bud/src/context/index.ts

@@ -36,6 +36,7 @@ export default async (options: Options = {}): Promise<Context> => {
   const files: Context[`files`] = await projectFiles.get(paths.basedir)
   const extensions: Context[`extensions`] = getExtensions(
     manifest,
+    args.use ?? [],
     options?.extensions,
   )