feat(plugin-completion): support Bun runtimes

Resolve completion script executables for Bun source execution and likely Bun single-file binaries while keeping Deno as an unsupported runtime path.

Split executable resolution into testable helpers, quote shell command parts consistently, and document the Bun compile heuristic with upstream references. Escape executable commands for the @bomb.sh/tab generated shell assignment before eval to avoid command substitution while preserving token quoting.

Author: ReoHakase

e2e/bun.spec.ts

@@ -1,7 +1,15 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import os from 'node:os'
 import path from 'node:path'
 import { expect, test } from 'vitest'
 import { runCommand } from '../scripts/utils.ts'
 
+const ROOT = path.resolve(import.meta.dirname, '..')
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll(`'`, `'\\''`)}'`
+}
+
 test('bun', async () => {
   // install dependencies
   await runCommand('bun install', {
@@ -12,3 +20,45 @@ test('bun', async () => {
   })
   expect(output).include(`Hello, Gunshi with Bun!`)
 })
+
+test('bun source completion', async () => {
+  const fixture = path.resolve(ROOT, 'packages/plugin-completion/examples/basic.node.ts')
+  const command = `bun ${shellQuote(fixture)}`
+  const script = await runCommand(`${command} complete zsh`, {
+    cwd: ROOT
+  })
+  expect(script).include('bun')
+
+  const output = await runCommand(`${command} complete -- --config vite.config`, {
+    cwd: ROOT
+  })
+  expect(output).include('vite.config.ts')
+})
+
+test('bun single binary completion', async () => {
+  const fixture = path.resolve(ROOT, 'packages/plugin-completion/examples/basic.node.ts')
+  const tmpDir = await mkdtemp(path.join(os.tmpdir(), 'gunshi-completion-bun-'))
+  const outfile = path.join(tmpDir, 'gunshi-completion-bun')
+
+  try {
+    await runCommand(
+      `bun build --compile ${shellQuote(fixture)} --outfile ${shellQuote(outfile)}`,
+      {
+        cwd: ROOT,
+        timeout: 60_000
+      }
+    )
+
+    const script = await runCommand(`${shellQuote(outfile)} complete zsh`, {
+      cwd: ROOT
+    })
+    expect(script).include(outfile)
+
+    const output = await runCommand(`${shellQuote(outfile)} complete -- --config vite.config`, {
+      cwd: ROOT
+    })
+    expect(output).include('vite.config.ts')
+  } finally {
+    await rm(tmpDir, { force: true, recursive: true })
+  }
+})

packages/plugin-completion/README.md

@@ -13,7 +13,7 @@ This completion plugin is powered by [`@bomb.sh/tab`](https://github.com/bombshe
 <!-- eslint-disable markdown/no-missing-label-refs -->
 
 > [!WARNING]
-> This package support Node.js runtime only. Deno and Bun support are coming soon.
+> This package support Node.js and Bun runtime only. Deno support is not available yet.
 
 <!-- eslint-enable markdown/no-missing-label-refs -->
 
@@ -116,20 +116,24 @@ The `complete` command accepts the following shell types:
 
 <!-- eslint-enable markdown/no-missing-label-refs -->
 
-## Shell Completion Setup
+### Runtime Support
 
-This section provides detailed instructions for setting up shell completions in different shells. The setup is a one-time process that enables tab completion for your CLI.
+The plugin supports completion script generation for Node.js, Bun source execution, and Bun single-file executables.
 
-### Prerequisites
+Runtime detection is intentionally conservative:
 
-Shell completion requires Node.js runtime. Ensure your CLI is running with Node.js (not Deno or Bun).
+- **Bun source execution** replays the current Bun executable, `process.execArgv`, and the source entry. This follows Bun's documented argument vector shape, where the launcher is first and the source file is second. See [Bun's `argv` guide](https://bun.com/guides/process/argv) and [single-file executable docs](https://bun.com/docs/bundler/executables).
+- **Bun single-file executables** call the compiled executable itself. Bun does not currently expose a stable runtime flag that says "this process is a compiled executable", so the plugin uses an internal heuristic based on `process.execPath` and Bun virtual entries. This avoids regenerating a completion script that tries to call the original source file from inside a compiled binary. The heuristic is intentionally private; related Bun compile behavior is discussed in [oven-sh/bun#14676](https://github.com/oven-sh/bun/issues/14676) and [oven-sh/bun#13405](https://github.com/oven-sh/bun/issues/13405).
 
-<!-- eslint-disable markdown/no-missing-label-refs -->
+Deno runtime completion script generation is not supported yet.
 
-> [!WARNING]
-> This package support Node.js runtime only. Deno and Bun support are coming soon.
+## Shell Completion Setup
 
-<!-- eslint-enable markdown/no-missing-label-refs -->
+This section provides detailed instructions for setting up shell completions in different shells. The setup is a one-time process that enables tab completion for your CLI.
+
+### Prerequisites
+
+Shell completion requires your CLI command to be executable from the generated completion script.
 
 ### Setup by Shell
 

packages/plugin-completion/docs/functions/default.md

@@ -7,7 +7,7 @@
 # Function: default()
 
 ```ts
-function default(options): PluginWithoutExtension;
+function default(options?): PluginWithoutExtension;
 ```
 
 completion plugin

packages/plugin-completion/docs/interfaces/CompletionConfig.md

@@ -12,5 +12,5 @@ Completion configuration, which structure is similar `bombsh/tab`'s `CompletionC
 
 | Property | Type | Description |
 | ------ | ------ | ------ |
-| <a id="args"></a> `args?` | `Record`\<`string`, \{ `handler`: [`CompletionHandler`](../type-aliases/CompletionHandler.md); \}\> | The command arguments for the completion. |
-| <a id="handler"></a> `handler?` | [`CompletionHandler`](../type-aliases/CompletionHandler.md) | The [`handler`](../type-aliases/CompletionHandler.md) for the completion. |
+| <a id="property-args"></a> `args?` | `Record`\<`string`, \{ `handler`: [`CompletionHandler`](../type-aliases/CompletionHandler.md); \}\> | The command arguments for the completion. |
+| <a id="property-handler"></a> `handler?` | [`CompletionHandler`](../type-aliases/CompletionHandler.md) | The [`handler`](../type-aliases/CompletionHandler.md) for the completion. |

packages/plugin-completion/docs/interfaces/CompletionOptions.md

@@ -12,6 +12,6 @@ Completion plugin options.
 
 | Property | Type | Description |
 | ------ | ------ | ------ |
-| <a id="config"></a> `config?` | `object` | The completion configuration |
+| <a id="property-config"></a> `config?` | `object` | The completion configuration |
 | `config.entry?` | [`CompletionConfig`](CompletionConfig.md) | The entry point [`completion configuration`](CompletionConfig.md). |
 | `config.subCommands?` | `Record`\<`string`, [`CompletionConfig`](CompletionConfig.md)\> | The handlers for sub-commands. |

packages/plugin-completion/docs/interfaces/CompletionParams.md

@@ -12,4 +12,4 @@ Parameters for [`the completion handler`](../type-aliases/CompletionHandler.md).
 
 | Property | Type | Description |
 | ------ | ------ | ------ |
-| <a id="locale"></a> `locale?` | `Locale` | The locale to use for i18n. |
+| <a id="property-locale"></a> `locale?` | `Locale` | The locale to use for i18n. |

packages/plugin-completion/docs/type-aliases/CompletionHandler.md

@@ -4,7 +4,7 @@
 
 [@gunshi/plugin-completion](../index.md) / CompletionHandler
 
-# Type Alias: CompletionHandler()
+# Type Alias: CompletionHandler
 
 ```ts
 type CompletionHandler = (params) => Completion[];

packages/plugin-completion/src/utils.test.ts

@@ -0,0 +1,153 @@
+/**
+ * @author kazuya kawaguchi (a.k.a. kazupon)
+ * @license MIT
+ */
+
+import { describe, expect, test } from 'vitest'
+import {
+  detectRuntime,
+  joinExecParts,
+  resolveBunExecParts,
+  resolveNodeExecParts,
+  shellQuote
+} from './utils.ts'
+
+import type { ProcessLike } from './utils.ts'
+
+function createProcess(overrides: Partial<ProcessLike> = {}): ProcessLike {
+  return {
+    argv: ['/usr/local/bin/node', './cli.ts'],
+    execArgv: [],
+    execPath: '/usr/local/bin/node',
+    release: {
+      name: 'node'
+    },
+    ...overrides
+  }
+}
+
+describe('detectRuntime', () => {
+  test('prioritizes Bun over Deno and Node-compatible process', () => {
+    expect(
+      detectRuntime({
+        Bun: {},
+        Deno: {},
+        process: createProcess()
+      })
+    ).toBe('bun')
+  })
+
+  test('prioritizes Deno over Node-compatible process', () => {
+    expect(
+      detectRuntime({
+        Deno: {},
+        process: createProcess()
+      })
+    ).toBe('deno')
+  })
+
+  test('detects Node from process release name', () => {
+    expect(
+      detectRuntime({
+        process: createProcess()
+      })
+    ).toBe('node')
+  })
+})
+
+describe('resolveNodeExecParts', () => {
+  test('resolves Node source execution', () => {
+    expect(resolveNodeExecParts(createProcess())).toEqual(['/usr/local/bin/node', './cli.ts'])
+  })
+})
+
+describe('resolveBunExecParts', () => {
+  test('resolves Bun source execution', () => {
+    expect(
+      resolveBunExecParts(
+        createProcess({
+          argv: ['/usr/local/bin/bun', './src/cli.ts'],
+          execPath: '/usr/local/bin/bun'
+        })
+      )
+    ).toEqual(['/usr/local/bin/bun', './src/cli.ts'])
+  })
+
+  test('resolves Bun source execution with execArgv', () => {
+    expect(
+      resolveBunExecParts(
+        createProcess({
+          argv: ['/usr/local/bin/bun', './src/cli.ts'],
+          execArgv: ['--smol'],
+          execPath: '/usr/local/bin/bun'
+        })
+      )
+    ).toEqual(['/usr/local/bin/bun', '--smol', './src/cli.ts'])
+  })
+
+  test('resolves Bun single binary on Unix', () => {
+    expect(
+      resolveBunExecParts(
+        createProcess({
+          argv: ['/tmp/my-cli'],
+          execPath: '/tmp/my-cli'
+        })
+      )
+    ).toEqual(['/tmp/my-cli'])
+  })
+
+  test('resolves Bun single binary on Windows', () => {
+    expect(
+      resolveBunExecParts(
+        createProcess({
+          argv: ['C:\\tools\\my-cli.exe'],
+          execPath: 'C:\\tools\\my-cli.exe'
+        })
+      )
+    ).toEqual(['C:\\tools\\my-cli.exe'])
+  })
+
+  test('resolves Bun Unix virtual compiled entry', () => {
+    expect(
+      resolveBunExecParts(
+        createProcess({
+          argv: ['/usr/local/bin/bun', '/$bunfs/root/main.js'],
+          execPath: '/usr/local/bin/bun'
+        })
+      )
+    ).toEqual(['/usr/local/bin/bun'])
+  })
+
+  test('resolves Bun Windows virtual compiled entry', () => {
+    expect(
+      resolveBunExecParts(
+        createProcess({
+          argv: ['C:\\tools\\bun.exe', 'B:\\~BUN\\root.js'],
+          execPath: 'C:\\tools\\bun.exe'
+        })
+      )
+    ).toEqual(['C:\\tools\\bun.exe'])
+  })
+})
+
+describe('shellQuote', () => {
+  test('escapes spaces and single quotes', () => {
+    expect(shellQuote("/tmp/my cli's/bin")).toBe(`'/tmp/my cli'\\''s/bin'`)
+  })
+
+  test('joins quoted exec parts without extra spaces', () => {
+    expect(joinExecParts(['/tmp/my cli/bin', "--flag=it's", './cli.ts'])).toBe(
+      String.raw`'/tmp/my cli/bin' '--flag=it'\\''s' ./cli.ts`
+    )
+  })
+
+  test('escapes metacharacters for generated double-quoted shell assignment', () => {
+    expect(
+      joinExecParts(['/tmp/$(touch pwn)/my cli', '--loader=`touch pwn`', './"quoted".ts'])
+    ).toBe("'/tmp/\\$(touch pwn)/my cli' '--loader=\\`touch pwn\\`' './\\\"quoted\\\".ts'")
+  })
+
+  test('preserves backslashes through generated double-quoted shell assignment', () => {
+    expect(joinExecParts(['C:\\tools\\my cli.exe'])).toBe("'C:\\\\tools\\\\my cli.exe'")
+  })
+})