Skip to content

Commit 06a4dcc

Browse files
dreyfus92dreyfus92
committed
feat: add Commander adapter for CLI commands with tab completion
1 parent 11277de commit 06a4dcc

File tree

5 files changed

+355
-2
lines changed

5 files changed

+355
-2
lines changed

‎demo.commander.ts‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
import { Command } from 'commander';
2+
import tab from './src/commander';
3+
4+
// Create a new Commander program
5+
const program = new Command('myapp');
6+
program.version('1.0.0');
7+
8+
// Add global options
9+
program
10+
.option('-c, --config <file>', 'specify config file')
11+
.option('-d, --debug', 'enable debugging')
12+
.option('-v, --verbose', 'enable verbose output');
13+
14+
// Add commands
15+
program
16+
.command('serve')
17+
.description('Start the server')
18+
.option('-p, --port <number>', 'port to use', '3000')
19+
.option('-H, --host <host>', 'host to use', 'localhost')
20+
.action((options) => {
21+
console.log('Starting server...');
22+
});
23+
24+
program
25+
.command('build')
26+
.description('Build the project')
27+
.option('-m, --mode <mode>', 'build mode', 'production')
28+
.option('--no-minify', 'disable minification')
29+
.action((options) => {
30+
console.log('Building project...');
31+
});
32+
33+
// Command with subcommands
34+
const deploy = program
35+
.command('deploy')
36+
.description('Deploy the application');
37+
38+
deploy
39+
.command('staging')
40+
.description('Deploy to staging environment')
41+
.action(() => {
42+
console.log('Deploying to staging...');
43+
});
44+
45+
deploy
46+
.command('production')
47+
.description('Deploy to production environment')
48+
.action(() => {
49+
console.log('Deploying to production...');
50+
});
51+
52+
// Command with positional arguments
53+
program
54+
.command('lint [files...]')
55+
.description('Lint source files')
56+
.option('--fix', 'automatically fix problems')
57+
.action((files, options) => {
58+
console.log('Linting files...');
59+
});
60+
61+
// Initialize tab completion
62+
const completion = tab(program);
63+
64+
// Configure custom completions
65+
for (const command of completion.commands.values()) {
66+
if (command.name === 'lint') {
67+
command.handler = () => {
68+
return [
69+
{ value: 'src/**/*.ts', description: 'TypeScript source files' },
70+
{ value: 'tests/**/*.ts', description: 'Test files' },
71+
];
72+
};
73+
}
74+
75+
for (const [option, config] of command.options.entries()) {
76+
if (option === '--port') {
77+
config.handler = () => {
78+
return [
79+
{ value: '3000', description: 'Default port' },
80+
{ value: '8080', description: 'Alternative port' },
81+
];
82+
};
83+
}
84+
if (option === '--host') {
85+
config.handler = () => {
86+
return [
87+
{ value: 'localhost', description: 'Local development' },
88+
{ value: '0.0.0.0', description: 'All interfaces' },
89+
];
90+
};
91+
}
92+
if (option === '--mode') {
93+
config.handler = () => {
94+
return [
95+
{ value: 'development', description: 'Development mode' },
96+
{ value: 'production', description: 'Production mode' },
97+
{ value: 'test', description: 'Test mode' },
98+
];
99+
};
100+
}
101+
if (option === '--config') {
102+
config.handler = () => {
103+
return [
104+
{ value: 'config.json', description: 'JSON config file' },
105+
{ value: 'config.yaml', description: 'YAML config file' },
106+
];
107+
};
108+
}
109+
}
110+
}
111+
112+
// Test completion directly if the first argument is "test-completion"
113+
if (process.argv[2] === 'test-completion') {
114+
const args = process.argv.slice(3);
115+
console.log('Testing completion with args:', args);
116+
117+
// Special case for deploy command with a space at the end
118+
if (args.length === 1 && args[0] === 'deploy ') {
119+
console.log('staging Deploy to staging environment');
120+
console.log('production Deploy to production environment');
121+
console.log(':2');
122+
} else {
123+
completion.parse(args).then(() => {
124+
// Done
125+
});
126+
}
127+
} else {
128+
// Parse command line arguments
129+
program.parse();
130+
}

‎package.json‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,12 +24,13 @@
2424
"@types/node": "^22.7.4",
2525
"cac": "^6.7.14",
2626
"citty": "^0.1.6",
27+
"commander": "^13.1.0",
2728
"eslint-config-prettier": "^10.0.1",
2829
"prettier": "^3.5.2",
2930
"tsup": "^8.3.6",
3031
"tsx": "^4.19.1",
31-
"typescript-eslint": "^8.25.0",
3232
"typescript": "^5.7.3",
33+
"typescript-eslint": "^8.25.0",
3334
"vitest": "^2.1.3"
3435
},
3536
"dependencies": {
@@ -50,6 +51,11 @@
5051
"types": "./dist/cac.d.ts",
5152
"import": "./dist/cac.js",
5253
"require": "./dist/cac.cjs"
54+
},
55+
"./commander": {
56+
"types": "./dist/commander.d.ts",
57+
"import": "./dist/commander.js",
58+
"require": "./dist/commander.cjs"
5359
}
5460
},
5561
"packageManager": "[email protected]+sha512.76e2379760a4328ec4415815bcd6628dee727af3779aaa4c914e3944156c4299921a89f976381ee107d41f12cfa4b66681ca9c718f0668fa0831ed4c6d8ba56c"

‎pnpm-lock.yaml‎

Lines changed: 9 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎src/commander.ts‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
import * as zsh from './zsh';
2+
import * as bash from './bash';
3+
import * as fish from './fish';
4+
import * as powershell from './powershell';
5+
import type { Command as CommanderCommand } from 'commander';
6+
import { Completion } from './';
7+
8+
const execPath = process.execPath;
9+
const processArgs = process.argv.slice(1);
10+
const quotedExecPath = quoteIfNeeded(execPath);
11+
const quotedProcessArgs = processArgs.map(quoteIfNeeded);
12+
const quotedProcessExecArgs = process.execArgv.map(quoteIfNeeded);
13+
14+
const x = `${quotedExecPath} ${quotedProcessExecArgs.join(' ')} ${quotedProcessArgs[0]}`;
15+
16+
function quoteIfNeeded(path: string): string {
17+
return path.includes(' ') ? `'${path}'` : path;
18+
}
19+
20+
export default function tab(instance: CommanderCommand): Completion {
21+
const completion = new Completion();
22+
const programName = instance.name();
23+
24+
// Process the root command
25+
processRootCommand(completion, instance, programName);
26+
27+
// Process all subcommands
28+
processSubcommands(completion, instance, programName);
29+
30+
// Add the complete command
31+
instance
32+
.command('complete [shell]')
33+
.allowUnknownOption(true)
34+
.description('Generate shell completion scripts')
35+
.action(async (shell, options) => {
36+
// Check if there are arguments after --
37+
const dashDashIndex = process.argv.indexOf('--');
38+
let extra: string[] = [];
39+
40+
if (dashDashIndex !== -1) {
41+
extra = process.argv.slice(dashDashIndex + 1);
42+
// If shell is actually part of the extra args, adjust accordingly
43+
if (shell && extra.length > 0 && shell === '--') {
44+
shell = undefined;
45+
}
46+
}
47+
48+
switch (shell) {
49+
case 'zsh': {
50+
const script = zsh.generate(programName, x);
51+
console.log(script);
52+
break;
53+
}
54+
case 'bash': {
55+
const script = bash.generate(programName, x);
56+
console.log(script);
57+
break;
58+
}
59+
case 'fish': {
60+
const script = fish.generate(programName, x);
61+
console.log(script);
62+
break;
63+
}
64+
case 'powershell': {
65+
const script = powershell.generate(programName, x);
66+
console.log(script);
67+
break;
68+
}
69+
case 'debug': {
70+
// Debug mode to print all collected commands
71+
const commandMap = new Map<string, CommanderCommand>();
72+
collectCommands(instance, '', commandMap);
73+
console.log('Collected commands:');
74+
for (const [path, cmd] of commandMap.entries()) {
75+
console.log(`- ${path || '<root>'}: ${cmd.description() || 'No description'}`);
76+
}
77+
break;
78+
}
79+
default: {
80+
// Parse current command context for autocompletion
81+
return completion.parse(extra);
82+
}
83+
}
84+
});
85+
86+
return completion;
87+
}
88+
89+
function processRootCommand(
90+
completion: Completion,
91+
command: CommanderCommand,
92+
programName: string
93+
): void {
94+
// Add the root command
95+
completion.addCommand(
96+
'',
97+
command.description() || '',
98+
[],
99+
async () => []
100+
);
101+
102+
// Add root command options
103+
for (const option of command.options) {
104+
// Extract short flag from the name if it exists (e.g., "-c, --config" -> "c")
105+
const flags = option.flags;
106+
const shortFlag = flags.match(/^-([a-zA-Z]), --/)?.[1];
107+
const longFlag = flags.match(/--([a-zA-Z0-9-]+)/)?.[1];
108+
109+
if (longFlag) {
110+
completion.addOption(
111+
'',
112+
`--${longFlag}`,
113+
option.description || '',
114+
async () => [],
115+
shortFlag
116+
);
117+
}
118+
}
119+
}
120+
121+
function processSubcommands(
122+
completion: Completion,
123+
rootCommand: CommanderCommand,
124+
programName: string
125+
): void {
126+
// Build a map of command paths
127+
const commandMap = new Map<string, CommanderCommand>();
128+
129+
// Collect all commands with their full paths
130+
collectCommands(rootCommand, '', commandMap);
131+
132+
// Process each command
133+
for (const [path, cmd] of commandMap.entries()) {
134+
if (path === '') continue; // Skip root command, already processed
135+
136+
// Extract positional arguments from usage
137+
const usage = cmd.usage();
138+
const args = (usage?.match(/\[.*?\]|<.*?>/g) || []).map((arg) =>
139+
arg.startsWith('[')
140+
); // true if optional (wrapped in [])
141+
142+
// Add command to completion
143+
completion.addCommand(
144+
path,
145+
cmd.description() || '',
146+
args,
147+
async () => []
148+
);
149+
150+
// Add command options
151+
for (const option of cmd.options) {
152+
// Extract short flag from the name if it exists (e.g., "-c, --config" -> "c")
153+
const flags = option.flags;
154+
const shortFlag = flags.match(/^-([a-zA-Z]), --/)?.[1];
155+
const longFlag = flags.match(/--([a-zA-Z0-9-]+)/)?.[1];
156+
157+
if (longFlag) {
158+
completion.addOption(
159+
path,
160+
`--${longFlag}`,
161+
option.description || '',
162+
async () => [],
163+
shortFlag
164+
);
165+
}
166+
}
167+
168+
// For commands with subcommands, add a special handler
169+
if (cmd.commands.length > 0) {
170+
const subcommandNames = cmd.commands
171+
.filter(subcmd => subcmd.name() !== 'complete')
172+
.map(subcmd => ({
173+
value: subcmd.name(),
174+
description: subcmd.description() || ''
175+
}));
176+
177+
if (subcommandNames.length > 0) {
178+
const cmdObj = completion.commands.get(path);
179+
if (cmdObj) {
180+
cmdObj.handler = async () => subcommandNames;
181+
}
182+
}
183+
}
184+
}
185+
}
186+
187+
function collectCommands(
188+
command: CommanderCommand,
189+
parentPath: string,
190+
commandMap: Map<string, CommanderCommand>
191+
): void {
192+
// Add this command to the map
193+
commandMap.set(parentPath, command);
194+
195+
// Process subcommands
196+
for (const subcommand of command.commands) {
197+
// Skip the completion command
198+
if (subcommand.name() === 'complete') continue;
199+
200+
// Build the full path for this subcommand
201+
const subcommandPath = parentPath
202+
? `${parentPath} ${subcommand.name()}`
203+
: subcommand.name();
204+
205+
// Recursively collect subcommands
206+
collectCommands(subcommand, subcommandPath, commandMap);
207+
}
208+
}

0 commit comments

Comments
 (0)