feat(rstack): add declarative CLI help renderer

README.md

@@ -12,19 +12,19 @@ Rstack CLI brings the Rstack toolchain together for JavaScript development, with
 
 It also covers local development needs outside Rstack's scope, with Prettier formatting and lint-staged commands.
 
-| Command                                             | Description                      |
-| --------------------------------------------------- | -------------------------------- |
-| [`rs dev`](https://rstack.rs/guide/cli/dev)         | Run the app dev server           |
-| [`rs build`](https://rstack.rs/guide/cli/build)     | Build the app for production     |
-| [`rs preview`](https://rstack.rs/guide/cli/preview) | Preview the app production build |
-| [`rs test`](https://rstack.rs/guide/cli/test)       | Run tests                        |
-| [`rs lint`](https://rstack.rs/guide/cli/lint)       | Lint code                        |
-| [`rs fmt`](https://rstack.rs/guide/cli/fmt)         | Format code                      |
-| [`rs check`](https://rstack.rs/guide/cli/check)     | Run static checks                |
-| [`rs lib`](https://rstack.rs/guide/cli/lib)         | Build library                    |
-| [`rs doc`](https://rstack.rs/guide/cli/doc)         | Serve or build docs              |
-| [`rs setup`](https://rstack.rs/guide/cli/setup)     | Install Git hooks                |
-| [`rs staged`](https://rstack.rs/guide/cli/staged)   | Run tasks on staged Git files    |
+| Command                                             | Description                                  |
+| --------------------------------------------------- | -------------------------------------------- |
+| [`rs dev`](https://rstack.rs/guide/cli/dev)         | Run the app dev server                       |
+| [`rs build`](https://rstack.rs/guide/cli/build)     | Build the app for production                 |
+| [`rs preview`](https://rstack.rs/guide/cli/preview) | Preview the app production build             |
+| [`rs test`](https://rstack.rs/guide/cli/test)       | Run tests                                    |
+| [`rs lint`](https://rstack.rs/guide/cli/lint)       | Lint code                                    |
+| [`rs fmt`](https://rstack.rs/guide/cli/fmt)         | Format code                                  |
+| [`rs check`](https://rstack.rs/guide/cli/check)     | Run static checks, including lint and format |
+| [`rs lib`](https://rstack.rs/guide/cli/lib)         | Build library                                |
+| [`rs doc`](https://rstack.rs/guide/cli/doc)         | Serve or build docs                          |
+| [`rs setup`](https://rstack.rs/guide/cli/setup)     | Install Git hooks                            |
+| [`rs staged`](https://rstack.rs/guide/cli/staged)   | Run tasks on staged Git files                |
 
 Rstack CLI fits into your existing project workflow. It does not replace your runtime, package manager, or task runner, such as [pnpm](https://github.com/pnpm/pnpm), [Bun](https://github.com/oven-sh/bun), [Turborepo](https://github.com/vercel/turborepo), [Nx](https://github.com/nrwl/nx), and [Nub](https://github.com/nubjs/nub).
 

packages/create-rstack/template-common/README.md

@@ -11,7 +11,7 @@ Install the dependencies:
 ## Scripts
 
 - `{{ packageManager }} run build`: Build the app for production.
-- `{{ packageManager }} run check`: Run static checks, including linting and formatting.
+- `{{ packageManager }} run check`: Run static checks, including lint and format.
 - `{{ packageManager }} run dev`: Run the app dev server.
 - `{{ packageManager }} run format`: Format code.
 - `{{ packageManager }} run lint`: Lint code.

packages/create-rstack/template-doc-i18n/README.md

@@ -11,7 +11,7 @@ Install the dependencies:
 ## Scripts
 
 - `{{ packageManager }} run build`: Build the documentation site for production.
-- `{{ packageManager }} run check`: Run static checks, including linting and formatting.
+- `{{ packageManager }} run check`: Run static checks, including lint and format.
 - `{{ packageManager }} run dev`: Start the documentation dev server.
 - `{{ packageManager }} run format`: Format code.
 - `{{ packageManager }} run lint`: Lint code.

packages/create-rstack/template-doc/README.md

@@ -11,7 +11,7 @@ Install the dependencies:
 ## Scripts
 
 - `{{ packageManager }} run build`: Build the documentation site for production.
-- `{{ packageManager }} run check`: Run static checks, including linting and formatting.
+- `{{ packageManager }} run check`: Run static checks, including lint and format.
 - `{{ packageManager }} run dev`: Start the documentation dev server.
 - `{{ packageManager }} run format`: Format code.
 - `{{ packageManager }} run lint`: Lint code.

packages/create-rstack/template-lib-node-ts/README.md

@@ -11,7 +11,7 @@ Install the dependencies:
 ## Scripts
 
 - `{{ packageManager }} run build`: Build the library.
-- `{{ packageManager }} run check`: Run static checks, including linting and formatting.
+- `{{ packageManager }} run check`: Run static checks, including lint and format.
 - `{{ packageManager }} run dev`: Build the library in watch mode.
 - `{{ packageManager }} run format`: Format code.
 - `{{ packageManager }} run lint`: Lint code.

packages/create-rstack/template-lib-node/README.md

@@ -11,7 +11,7 @@ Install the dependencies:
 ## Scripts
 
 - `{{ packageManager }} run build`: Build the library.
-- `{{ packageManager }} run check`: Run static checks, including linting and formatting.
+- `{{ packageManager }} run check`: Run static checks, including lint and format.
 - `{{ packageManager }} run dev`: Build the library in watch mode.
 - `{{ packageManager }} run format`: Format code.
 - `{{ packageManager }} run lint`: Lint code.

packages/create-rstack/template-lib-react-ts/README.md

@@ -11,7 +11,7 @@ Install the dependencies:
 ## Scripts
 
 - `{{ packageManager }} run build`: Build the library.
-- `{{ packageManager }} run check`: Run static checks, including linting and formatting.
+- `{{ packageManager }} run check`: Run static checks, including lint and format.
 - `{{ packageManager }} run dev`: Build the library in watch mode.
 - `{{ packageManager }} run format`: Format code.
 - `{{ packageManager }} run lint`: Lint code.

packages/create-rstack/template-lib-react/README.md

@@ -11,7 +11,7 @@ Install the dependencies:
 ## Scripts
 
 - `{{ packageManager }} run build`: Build the library.
-- `{{ packageManager }} run check`: Run static checks, including linting and formatting.
+- `{{ packageManager }} run check`: Run static checks, including lint and format.
 - `{{ packageManager }} run dev`: Build the library in watch mode.
 - `{{ packageManager }} run format`: Format code.
 - `{{ packageManager }} run lint`: Lint code.

packages/create-rstack/template-lib-solid-ts/README.md

@@ -11,7 +11,7 @@ Install the dependencies:
 ## Scripts
 
 - `{{ packageManager }} run build`: Build the library.
-- `{{ packageManager }} run check`: Run static checks, including linting and formatting.
+- `{{ packageManager }} run check`: Run static checks, including lint and format.
 - `{{ packageManager }} run dev`: Build the library in watch mode.
 - `{{ packageManager }} run format`: Format code.
 - `{{ packageManager }} run lint`: Lint code.

packages/create-rstack/template-lib-solid/README.md

@@ -11,7 +11,7 @@ Install the dependencies:
 ## Scripts
 
 - `{{ packageManager }} run build`: Build the library.
-- `{{ packageManager }} run check`: Run static checks, including linting and formatting.
+- `{{ packageManager }} run check`: Run static checks, including lint and format.
 - `{{ packageManager }} run dev`: Build the library in watch mode.
 - `{{ packageManager }} run format`: Format code.
 - `{{ packageManager }} run lint`: Lint code.

packages/create-rstack/template-lib-svelte-ts/README.md

@@ -11,7 +11,7 @@ Install the dependencies:
 ## Scripts
 
 - `{{ packageManager }} run build`: Build the library.
-- `{{ packageManager }} run check`: Run static checks, including linting and formatting.
+- `{{ packageManager }} run check`: Run static checks, including lint and format.
 - `{{ packageManager }} run dev`: Build the library in watch mode.
 - `{{ packageManager }} run format`: Format code.
 - `{{ packageManager }} run lint`: Lint code.

packages/create-rstack/template-lib-svelte/README.md

@@ -11,7 +11,7 @@ Install the dependencies:
 ## Scripts
 
 - `{{ packageManager }} run build`: Build the library.
-- `{{ packageManager }} run check`: Run static checks, including linting and formatting.
+- `{{ packageManager }} run check`: Run static checks, including lint and format.
 - `{{ packageManager }} run dev`: Build the library in watch mode.
 - `{{ packageManager }} run format`: Format code.
 - `{{ packageManager }} run lint`: Lint code.

packages/create-rstack/template-lib-vue-ts/README.md

@@ -11,7 +11,7 @@ Install the dependencies:
 ## Scripts
 
 - `{{ packageManager }} run build`: Build the library.
-- `{{ packageManager }} run check`: Run static checks, including linting and formatting.
+- `{{ packageManager }} run check`: Run static checks, including lint and format.
 - `{{ packageManager }} run dev`: Build the library in watch mode.
 - `{{ packageManager }} run format`: Format code.
 - `{{ packageManager }} run lint`: Lint code.

packages/create-rstack/template-lib-vue/README.md

@@ -11,7 +11,7 @@ Install the dependencies:
 ## Scripts
 
 - `{{ packageManager }} run build`: Build the library.
-- `{{ packageManager }} run check`: Run static checks, including linting and formatting.
+- `{{ packageManager }} run check`: Run static checks, including lint and format.
 - `{{ packageManager }} run dev`: Build the library in watch mode.
 - `{{ packageManager }} run format`: Format code.
 - `{{ packageManager }} run lint`: Lint code.

packages/rstack/src/cli/commands.ts

@@ -1,48 +1,58 @@
 import { join } from 'node:path';
-import { color } from 'rslog';
 import { getConfigState } from '../config.ts';
 import { insertConfigArg, parseArgs, parseCliArgs } from './args.ts';
+import { renderHelp } from './help.ts';
+
+const renderRootHelp = (): string =>
+  renderHelp({
+    usage: 'rs [command] [...options]',
+    sections: [
+      {
+        title: 'Commands',
+        items: [
+          ['dev', 'Run the app dev server'],
+          ['build', 'Build the app for production'],
+          ['preview', 'Preview the app production build'],
+          ['lib', 'Build library'],
+          ['doc', 'Serve or build docs'],
+          ['fmt, format', 'Format code'],
+          ['lint', 'Lint code'],
+          ['check', 'Run static checks, including lint and format'],
+          ['test', 'Run tests'],
+          ['staged', 'Run tasks on staged Git files'],
+          ['setup', 'Install Git hooks'],
+        ],
+      },
+      {
+        content: `For command-specific options, run:
+  $ rs <command> -h`,
+        dim: true,
+      },
+      {
+        title: 'Options',
+        items: [
+          ['-c, --config <path>', 'Specify Rstack config file path'],
+          ['-h, --help', 'Display this help message'],
+          ['-v, --version', 'Display version number'],
+        ],
+      },
+    ],
+  });
 
-declare global {
-  const RSTACK_VERSION: string;
-}
-
-const helpMessage = `Rstack v${RSTACK_VERSION}
-
-${color.cyan('Usage')}:
-${color.yellow('  $ rs [command] [...options]')}
-
-${color.cyan('Commands')}:
-  dev          Run the app dev server
-  build        Build the app for production
-  preview      Preview the app production build
-  lib          Build library
-  doc          Serve or build docs
-  fmt, format  Format code
-  lint         Lint code
-  check        Run static checks, including linting and formatting
-  test         Run tests
-  staged       Run tasks on staged Git files
-  setup        Install Git hooks
-
-${color.dim(`For command-specific options, run:
-  $ rs <command> -h`)}
-
-${color.cyan('Options')}:
-  -c, --config <path>       Specify Rstack config file path
-  -h, --help                Display this help message
-  -v, --version             Display version number`;
-
-const checkHelpMessage = `Rstack v${RSTACK_VERSION}
-
-${color.cyan('Usage')}:
-${color.yellow('  $ rs check [options]')}
-
-Run static checks, including linting and formatting.
-
-${color.cyan('Options')}:
-  --type-check  Enable TypeScript type checking
-  -h, --help    Display this help message`;
+const renderCheckHelp = (): string =>
+  renderHelp({
+    usage: 'rs check [options]',
+    description: 'Run static checks, including lint and format',
+    sections: [
+      {
+        title: 'Options',
+        items: [
+          ['--type-check', 'Enable TypeScript type checking'],
+          ['-h, --help', 'Display this help message'],
+        ],
+      },
+    ],
+  });
 
 async function runRsbuildCLI(args: string[]): Promise<void> {
   const argv = [
@@ -130,7 +140,7 @@ async function runCheckCLI(args: string[]): Promise<void> {
   });
 
   if (values.help) {
-    console.log(checkHelpMessage);
+    console.log(renderCheckHelp());
     return;
   }
 
@@ -153,7 +163,7 @@ export async function setupCommands(): Promise<void> {
   getConfigState().configPath = configPath;
 
   if (!command || command === '-h' || command === '--help') {
-    console.log(helpMessage);
+    console.log(renderRootHelp());
     return;
   }
 

packages/rstack/src/cli/help.ts

@@ -0,0 +1,54 @@
+import { color } from 'rslog';
+
+declare global {
+  const RSTACK_VERSION: string;
+}
+
+export type HelpItem = readonly [label: string, description: string];
+
+export type HelpSection =
+  | {
+      title: string;
+      items: readonly HelpItem[];
+    }
+  | {
+      content: string;
+      dim?: boolean;
+    };
+
+export type HelpDefinition = {
+  usage: string;
+  description?: string;
+  sections?: readonly HelpSection[];
+};
+
+const renderItems = (items: readonly HelpItem[]): string => {
+  const labelWidth = items.reduce((width, [label]) => Math.max(width, label.length), 0);
+
+  return items
+    .map(([label, description]) => `  ${label.padEnd(labelWidth)}  ${description}`)
+    .join('\n');
+};
+
+const renderSection = (section: HelpSection): string => {
+  if ('items' in section) {
+    return `${color.cyan(section.title)}:\n${renderItems(section.items)}`;
+  }
+
+  return section.dim ? color.dim(section.content) : section.content;
+};
+
+export const renderHelp = ({ usage, description, sections = [] }: HelpDefinition): string => {
+  const blocks = [
+    color.bold(`Rstack v${RSTACK_VERSION}`),
+    `${color.cyan('Usage')}:\n${color.yellow(`  $ ${usage}`)}`,
+  ];
+
+  if (description) {
+    blocks.push(description);
+  }
+
+  blocks.push(...sections.map(renderSection));
+
+  return blocks.join('\n\n');
+};

packages/rstack/src/fmt/cli.ts

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { performance } from 'node:perf_hooks';
 import { color, logger } from 'rslog';
 import { parseArgs } from '../cli/args.ts';
+import { renderHelp } from '../cli/help.ts';
 import { loadRstackConfig } from '../config.ts';
 import { ensureProjectCacheDir } from '../projectCache.ts';
 import { fmtCacheFileName } from './cacheStore.ts';
@@ -26,26 +27,30 @@ interface ParsedFmtCLIArgs {
   stdinFilepath?: string;
 }
 
-const fmtHelpMessage: string = `Rstack v${RSTACK_VERSION}
-
-${color.cyan('Usage')}:
-${color.yellow('  $ rs fmt [options] [files/globs...]')}
-
-Format files with Prettier.
-
-${color.cyan('Options')}:
-  -w, --write                      Write formatted files in place (default)
-  --check                          Check whether files are formatted
-  -l, --list-different             Print paths of unformatted files
-  --ignore-path <path>             Path to an additional ignore file (repeatable)
-  -u, --ignore-unknown             Ignore unknown files
-  --no-cache                       Disable the formatting cache
-  --cache-location <path>          Path to the formatting cache directory
-  --no-error-on-unmatched-pattern  Do not error when no files match
-  --with-node-modules              Process files inside node_modules
-  --parallel-workers <count>       Number of parallel workers
-  --stdin-filepath <path>          Format stdin as if it were saved at <path>
-  -h, --help                       Display this help message`;
+const renderFmtHelp = (): string =>
+  renderHelp({
+    usage: 'rs fmt [options] [files/globs...]',
+    description: 'Format code',
+    sections: [
+      {
+        title: 'Options',
+        items: [
+          ['-w, --write', 'Write formatted files in place (default)'],
+          ['--check', 'Check whether files are formatted'],
+          ['-l, --list-different', 'Print paths of unformatted files'],
+          ['--ignore-path <path>', 'Path to an additional ignore file (repeatable)'],
+          ['-u, --ignore-unknown', 'Ignore unknown files'],
+          ['--no-cache', 'Disable the formatting cache'],
+          ['--cache-location <path>', 'Path to the formatting cache directory'],
+          ['--no-error-on-unmatched-pattern', 'Do not error when no files match'],
+          ['--with-node-modules', 'Process files inside node_modules'],
+          ['--parallel-workers <count>', 'Number of parallel workers'],
+          ['--stdin-filepath <path>', 'Format stdin as if it were saved at <path>'],
+          ['-h, --help', 'Display this help message'],
+        ],
+      },
+    ],
+  });
 
 const parseMaxWorkers = (value: string | undefined): number | undefined => {
   if (value === undefined) {
@@ -268,7 +273,7 @@ const runFmtCLI = async (args: string[]): Promise<void> => {
       withNodeModules,
     } = parseFmtCLIArgs(args);
     if (help) {
-      logger.log(fmtHelpMessage);
+      logger.log(renderFmtHelp());
       return;
     }