An option is resolved from the root before the matched command, so a short name means one thing for the whole line

[kazupon]

What happens

RootCommand#shouldCompleteFlags() and #stripOptions() decide whether the word after an option is that option's value. Both resolve the option with findOption(this, arg) — the root first — and fall back to the registered commands only when the root does not have it. An option therefore has one arity for the whole line, whichever command the cursor is in.

A CLI whose root carries the program's own options, and whose sub-command gives one of those letters to an option that takes a value, cannot be completed there.

Reproduction

// repro.mjs — `npm i @bomb.sh/tab@0.0.22`, then `node repro.mjs`
import { RootCommand } from '@bomb.sh/tab'

const build = () => {
  const root = new RootCommand()
  root.option('help', 'Display this help message', 'h') // boolean, takes no value

  const serve = root.command('serve', 'Serve the app')
  serve.option('host', 'Host name', c => c('localhost', ''), 'h') // takes a value, same letter
  serve.argument('env', c => {
    c('prod', '')
    c('staging', '')
  })
  return root
}

for (const argv of [
  ['serve', '-h', ''],
  ['serve', '-h', 'localhost', ''],
  ['serve', '--host', ''],
  ['-h', '']
]) {
  process.stdout.write(`${JSON.stringify(argv).padEnd(36)} => `)
  build().parse([...argv])
}

Actual output (@bomb.sh/tab 0.0.22, Node 24.21.0). Each request prints its candidates one per line; they are joined with / here:

["serve","-h",""]                    => prod / staging / :4
["serve","-h","localhost",""]        => :4
["serve","--host",""]                => localhost / :4
["-h",""]                            => serve / :4

• serve -h <TAB> offers the positional, because -h was read as the root's boolean help. Expected: localhost, the value of the command's --host.
• serve -h localhost <TAB> offers nothing, because localhost was counted as the positional. Expected: prod, staging.
• The last two lines are the controls, and both are right: the long name resolves against the command, and -h in front of a command name is the root's.

Why it is not simply "look at the matched command"

stripOptions() is what matchCommand() calls to find the command, so the command is not known when the question is asked. Fixing it means walking the words in order and resolving each option against the command that is settled at that point — the root until a command name is matched, then that command, and so on.

handleFlagCompletion() already resolves against the matched command, so once shouldCompleteFlags() answers correctly for a letter typed behind a command name, the value completion follows.

Related

Issue #110 (closed) is the same family: handlePositionalCompletion() counted words without stripping options. This is the other half — the stripping itself does not know where it is.

Downstream

gunshi (kazupon/gunshi#744) works around it by re-registering the root's entry for that one letter, for the duration of one completion request, and only when the letter was typed behind the matched command's name
(PR #753, corrected in PR #754 — the first attempt re-registered the root's entry under the option's long name, which flipped the arity of --help too). The workaround cannot express the same letter on both sides of a command name, because one Option carries one arity for the request. If the lookup here becomes positional, that workaround is deleted whole.

[shadowspawn]

The correct lookup behaviour will vary depending on the parsing engine, and potentially the parsing configuration. (Disclaimer: I have read the description here, but am not familiar with the implementation.)

The default behaviour in Commander is that options on the root command are global, and effectively mask a matching option in a subcommand. So the root options should be completed both before and after the subcommand name.

The default behaviour can be changed by calling cmd.enablePositionalOptions(). This makes root options only recognised before the subcommand name.

(I say root in the description for simplicity, but this is true in general of a command and its subcommands when there is more than one layer of subcommands.)