feat: add onBeforeCommand to run tasks before agent detection (#318)

Author: sushichan044

src/runner.ts

@@ -27,9 +27,25 @@ export interface ExtendedResolvedCommand extends ResolvedCommand {
   cwd?: string
 }
 
+interface RunOptions {
+  /**
+   * Called before agent detection and command execution.
+   *
+   * Useful for performing concrete, agent-agnostic operations.
+   */
+  onBeforeCommand?: (args: string[], ctx: Pick<RunnerContext, 'cwd' | 'programmatic'> & {
+    /**
+     * Skips subsequent command execution.
+     *
+     * This is useful for operations such as generating shell-completion scripts.
+     */
+    exit: () => void
+  }) => void | Promise<void>
+}
+
 export type Runner = (agent: Agent, args: string[], ctx?: RunnerContext) => Promise<ExtendedResolvedCommand | undefined> | ExtendedResolvedCommand | undefined
 
-export async function runCli(fn: Runner, options: DetectOptions & { args?: string[] } = {}) {
+export async function runCli(fn: Runner, options: DetectOptions & RunOptions & { args?: string[] } = {}) {
   options = {
     ...getEnvironmentOptions(),
     ...options,
@@ -82,7 +98,7 @@ export async function getCliCommand(
   })
 }
 
-export async function run(fn: Runner, args: string[], options: DetectOptions = {}) {
+export async function run(fn: Runner, args: string[], options: DetectOptions & RunOptions = {}) {
   const { programmatic, detectVolta = true } = options
 
   const debug = args.includes(DEBUG_SIGN)
@@ -146,6 +162,17 @@ export async function run(fn: Runner, args: string[], options: DetectOptions = {
     return
   }
 
+  if (options.onBeforeCommand) {
+    let shouldExit = false
+    await options.onBeforeCommand(args, {
+      cwd,
+      programmatic,
+      exit: () => { shouldExit = true },
+    })
+    if (shouldExit)
+      return
+  }
+
   const command = await getCliCommand(fn, args, options, cwd)
 
   if (!command)

test/runner/runCli.test.ts

@@ -5,23 +5,20 @@ import { runCli } from '../../src'
 // Mock detect to see what options are passed to it
 const mocks = vi.hoisted(() => ({
   detectSpy: vi.fn(() => Promise.resolve('npm')),
+  baseRunFnSpy: vi.fn<Runner>(() => Promise.resolve(undefined)),
 }))
 vi.mock('../../src/detect', () => ({
   detect: mocks.detectSpy,
 }))
 
-const baseRunFn: Runner = async () => {
-  return undefined
-}
-
 describe('runCli', () => {
   afterEach(() => {
     vi.clearAllMocks()
     vi.unstubAllEnvs()
   })
 
   it('run without errors', async () => {
-    const result = await runCli(baseRunFn, {})
+    const result = await runCli(mocks.baseRunFnSpy, {})
     expect(result).toBe(undefined)
   })
 
@@ -34,24 +31,38 @@ describe('runCli', () => {
   })
 
   it('calls detect with the correct options', async () => {
-    await runCli(baseRunFn)
+    await runCli(mocks.baseRunFnSpy)
     expect(mocks.detectSpy).toHaveBeenCalledWith({ autoInstall: false, cwd: expect.any(String) })
   })
 
   it('detects environment options', async () => {
     vi.stubEnv('NI_AUTO_INSTALL', 'true')
-    await runCli(baseRunFn)
+    await runCli(mocks.baseRunFnSpy)
     expect(mocks.detectSpy).toHaveBeenCalledWith({ autoInstall: true, cwd: expect.any(String) })
   })
 
   it('accept options as input', async () => {
-    await runCli(baseRunFn, { autoInstall: true, programmatic: true })
+    await runCli(mocks.baseRunFnSpy, { autoInstall: true, programmatic: true })
     expect(mocks.detectSpy).toHaveBeenCalledWith({ autoInstall: true, programmatic: true, cwd: expect.any(String) })
   })
 
   it('merges inputs and environment prioritizing inputs', async () => {
     vi.stubEnv('NI_AUTO_INSTALL', 'true')
-    await runCli(baseRunFn, { autoInstall: false, programmatic: true })
+    await runCli(mocks.baseRunFnSpy, { autoInstall: false, programmatic: true })
     expect(mocks.detectSpy).toHaveBeenCalledWith({ autoInstall: false, programmatic: true, cwd: expect.any(String) })
   })
+
+  describe('onBeforeCommand', () => {
+    it('skips running the command when exit() is called', async () => {
+      await runCli(mocks.baseRunFnSpy, { onBeforeCommand: (_args, ctx) => ctx.exit() })
+      expect(mocks.baseRunFnSpy).not.toHaveBeenCalled()
+      // https://github.com/antfu-collective/ni/issues/308
+      expect(mocks.detectSpy).not.toHaveBeenCalled()
+    })
+
+    it('continues to run the command when exit() is not called', async () => {
+      await runCli(mocks.baseRunFnSpy, { onBeforeCommand: () => Promise.resolve() })
+      expect(mocks.baseRunFnSpy).toHaveBeenCalledOnce()
+    })
+  })
 })