feat(cli): add command-specific help topics

Author: pallyoung

README.en.md

@@ -76,6 +76,7 @@ coder-studio config root set /srv/coder-studio/workspaces
 coder-studio config password set --stdin
 coder-studio auth status
 coder-studio auth ip list
+coder-studio help start
 ```
 
 For the detailed command reference, see `docs/development/cli.en.md`.

README.md

@@ -75,6 +75,7 @@ coder-studio config root set /srv/coder-studio/workspaces
 coder-studio config password set --stdin
 coder-studio auth status
 coder-studio auth ip list
+coder-studio help start
 ```
 
 详细命令说明见：`docs/development/cli.md`

docs/development/cli.en.md

@@ -80,6 +80,15 @@ Version:
 coder-studio --version
 ```
 
+Help:
+
+```bash
+coder-studio help
+coder-studio help start
+coder-studio help config
+coder-studio help auth
+```
+
 ## Global Flags
 
 Most runtime commands support:

docs/development/cli.md

@@ -80,6 +80,15 @@ coder-studio auth ip unblock --all
 coder-studio --version
 ```
 
+帮助：
+
+```bash
+coder-studio help
+coder-studio help start
+coder-studio help config
+coder-studio help auth
+```
+
 ## 全局参数
 
 大部分运行时命令支持：

packages/coder-studio/lib/cli.mjs

@@ -96,6 +96,7 @@ function printHelp() {
   console.log(`Coder Studio CLI
 
 Usage:
+  coder-studio help [command]
   coder-studio start [--host 127.0.0.1] [--port 41033] [--foreground] [--json]
   coder-studio stop [--json]
   coder-studio restart [--json]
@@ -119,6 +120,7 @@ Exit Codes:
   2  usage or argument error
 
 Examples:
+  coder-studio help start
   coder-studio start
   coder-studio config show --json
   coder-studio config root set /srv/coder-studio/workspaces
@@ -128,6 +130,123 @@ Run \`coder-studio config --help\` or \`coder-studio auth --help\` for detailed
 `);
 }
 
+function printStartHelp() {
+  console.log(`coder-studio start
+
+Usage:
+  coder-studio start [--host <host>] [--port <port>] [--foreground] [--json]
+
+Options:
+  --host <host>   override configured host for this invocation
+  --port <port>   override configured port for this invocation
+  --foreground    keep the runtime in the foreground
+  --json          machine-readable output
+
+Examples:
+  coder-studio start
+  coder-studio start --foreground
+  coder-studio start --port 42033 --json
+`);
+}
+
+function printStopHelp() {
+  console.log(`coder-studio stop
+
+Usage:
+  coder-studio stop [--json]
+
+Options:
+  --json  machine-readable output
+
+Examples:
+  coder-studio stop
+  coder-studio stop --json
+`);
+}
+
+function printRestartHelp() {
+  console.log(`coder-studio restart
+
+Usage:
+  coder-studio restart [--json]
+
+Options:
+  --json  machine-readable output
+
+Examples:
+  coder-studio restart
+  coder-studio restart --json
+`);
+}
+
+function printStatusHelp() {
+  console.log(`coder-studio status
+
+Usage:
+  coder-studio status [--host <host>] [--port <port>] [--json]
+
+Options:
+  --host <host>  override configured host for this invocation
+  --port <port>  override configured port for this invocation
+  --json         machine-readable output
+
+Examples:
+  coder-studio status
+  coder-studio status --json
+`);
+}
+
+function printLogsHelp() {
+  console.log(`coder-studio logs
+
+Usage:
+  coder-studio logs [-f] [-n <lines>]
+
+Options:
+  -f, --follow     follow the runtime log
+  -n, --lines <n>  read the last <n> lines
+
+Examples:
+  coder-studio logs
+  coder-studio logs -n 200
+  coder-studio logs -f
+`);
+}
+
+function printOpenHelp() {
+  console.log(`coder-studio open
+
+Usage:
+  coder-studio open [--host <host>] [--port <port>] [--json]
+
+Options:
+  --host <host>  override configured host for this invocation
+  --port <port>  override configured port for this invocation
+  --json         machine-readable output
+
+Examples:
+  coder-studio open
+  coder-studio open --json
+`);
+}
+
+function printDoctorHelp() {
+  console.log(`coder-studio doctor
+
+Usage:
+  coder-studio doctor [--host <host>] [--port <port>] [--json]
+
+Options:
+  --host <host>  override configured host for this invocation
+  --port <port>  override configured port for this invocation
+  --json         machine-readable output
+
+Examples:
+  coder-studio doctor
+  coder-studio doctor --json
+`);
+}
+
 function printConfigHelp() {
   console.log(`coder-studio config
 
@@ -172,6 +291,46 @@ Examples:
 `);
 }
 
+function printHelpTopic(topic) {
+  switch (topic) {
+    case undefined:
+    case null:
+    case '':
+    case 'main':
+      printHelp();
+      return EXIT_SUCCESS;
+    case 'start':
+      printStartHelp();
+      return EXIT_SUCCESS;
+    case 'stop':
+      printStopHelp();
+      return EXIT_SUCCESS;
+    case 'restart':
+      printRestartHelp();
+      return EXIT_SUCCESS;
+    case 'status':
+      printStatusHelp();
+      return EXIT_SUCCESS;
+    case 'logs':
+      printLogsHelp();
+      return EXIT_SUCCESS;
+    case 'open':
+      printOpenHelp();
+      return EXIT_SUCCESS;
+    case 'doctor':
+      printDoctorHelp();
+      return EXIT_SUCCESS;
+    case 'config':
+      printConfigHelp();
+      return EXIT_SUCCESS;
+    case 'auth':
+      printAuthHelp();
+      return EXIT_SUCCESS;
+    default:
+      throw usageError(`unsupported help topic: ${topic}`, 'main');
+  }
+}
+
 function printStatus(status) {
   console.log(`status: ${status.status}`);
   console.log(`managed: ${status.managed ? 'yes' : 'no'}`);
@@ -734,17 +893,20 @@ function printCliError(error, flags) {
 export async function runCli(argv = process.argv.slice(2)) {
   const { command, flags, positionals } = parseArgv(argv);
 
-  if (command === '--version' || command === '-v' || flags.version) {
-    console.log(await readPackageVersion());
-    return EXIT_SUCCESS;
-  }
+  try {
+    if (command === '--version' || command === '-v' || flags.version) {
+      console.log(await readPackageVersion());
+      return EXIT_SUCCESS;
+    }
 
-  if (command === 'help' || flags.help && !['config', 'auth'].includes(command)) {
-    printHelp();
-    return EXIT_SUCCESS;
-  }
+    if (command === 'help') {
+      return printHelpTopic(positionals[0]);
+    }
+
+    if (flags.help) {
+      return printHelpTopic(command);
+    }
 
-  try {
     if (command === 'config') {
       const context = await resolveCommandContext(flags);
       return await handleConfigCommand(positionals, flags, context);

tests/cli/config.test.mjs

@@ -142,17 +142,36 @@ test('validateConfigSnapshot reports missing root when public mode is enabled',
 test('cli help documents exit codes and common examples', async () => {
   const result = await runCli(['help']);
   assert.match(result.stdout, /Exit Codes:/);
+  assert.match(result.stdout, /coder-studio help start/);
   assert.match(result.stdout, /coder-studio config show --json/);
   assert.match(result.stdout, /coder-studio auth ip list/);
 });
 
+test('cli supports dedicated help topics', async () => {
+  const startHelp = await runCli(['help', 'start']);
+  assert.match(startHelp.stdout, /^coder-studio start/m);
+  assert.match(startHelp.stdout, /--foreground/);
+
+  const configHelp = await runCli(['config', '--help']);
+  assert.match(configHelp.stdout, /^coder-studio config/m);
+
+  const commandHelp = await runCli(['start', '--help']);
+  assert.match(commandHelp.stdout, /^coder-studio start/m);
+});
+
 test('cli returns usage exit code and hint for unsupported commands', async () => {
   const result = await runCli(['wat'], { allowFailure: true });
   assert.equal(result.code, 2);
   assert.match(result.stderr, /unsupported command: wat/);
   assert.match(result.stderr, /coder-studio help/);
 });
 
+test('cli returns usage exit code for unsupported help topics', async () => {
+  const result = await runCli(['help', 'wat'], { allowFailure: true });
+  assert.equal(result.code, 2);
+  assert.match(result.stderr, /unsupported help topic: wat/);
+});
+
 test('cli returns usage exit code in json mode for invalid config usage', async () => {
   const result = await runCli(['config', 'set', 'server.port'], { allowFailure: true });
   assert.equal(result.code, 2);