From a4a74ab70cd2aa0d812a1f6b202c4e240a8913bf Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Mon, 6 Mar 2023 16:58:56 +0000 Subject: [PATCH] feat(cli): add help flags to various commands (#6394) Co-authored-by: Happydev <81974850+MoustaphaDev@users.noreply.github.com> --- .changeset/old-rivers-remember.md | 5 ++++ packages/astro/src/cli/check/index.ts | 21 +++++++++++-- packages/astro/src/cli/index.ts | 38 +++++++++++++++++------- packages/astro/src/cli/telemetry.ts | 2 +- packages/astro/src/core/build/index.ts | 18 +++++++++++ packages/astro/src/core/dev/dev.ts | 25 ++++++++++++++-- packages/astro/src/core/preview/index.ts | 22 ++++++++++++-- packages/astro/src/core/sync/index.ts | 16 +++++++++- 8 files changed, 128 insertions(+), 19 deletions(-) create mode 100644 .changeset/old-rivers-remember.md diff --git a/.changeset/old-rivers-remember.md b/.changeset/old-rivers-remember.md new file mode 100644 index 000000000..10340061b --- /dev/null +++ b/.changeset/old-rivers-remember.md @@ -0,0 +1,5 @@ +--- +'astro': minor +--- + +Add `--help` to various commands: `check`, `sync`, `dev`, `preview`, and `build` diff --git a/packages/astro/src/cli/check/index.ts b/packages/astro/src/cli/check/index.ts index 069ce343c..3104cdca5 100644 --- a/packages/astro/src/cli/check/index.ts +++ b/packages/astro/src/cli/check/index.ts @@ -2,7 +2,6 @@ import { AstroCheck, DiagnosticSeverity } from '@astrojs/language-server'; import type { AstroSettings } from '../../@types/astro'; import type { LogOptions } from '../../core/logger/core.js'; - import glob from 'fast-glob'; import * as fs from 'fs'; import { bold, dim, red, yellow } from 'kleur/colors'; @@ -10,6 +9,8 @@ import { createRequire } from 'module'; import ora from 'ora'; import { fileURLToPath, pathToFileURL } from 'url'; import { printDiagnostic } from './print.js'; +import { Arguments } from 'yargs-parser'; +import { printHelp } from '../../core/messages.js'; interface Result { errors: number; @@ -18,11 +19,25 @@ interface Result { hints: number; } -export async function check(settings: AstroSettings, { logging }: { logging: LogOptions }) { +export async function check( + settings: AstroSettings, + { logging, flags }: { logging: LogOptions; flags: Arguments } +) { + if (flags.help || flags.h) { + printHelp({ + commandName: 'astro check', + usage: '[...flags]', + tables: { + Flags: [['--help (-h)', 'See all available flags.']], + }, + description: `Runs diagnostics against your project and reports errors to the console.`, + }); + return; + } console.log(bold('astro check')); const { syncCli } = await import('../../core/sync/index.js'); - const syncRet = await syncCli(settings, { logging, fs }); + const syncRet = await syncCli(settings, { logging, fs, flags }); // early exit on sync failure if (syncRet === 1) return syncRet; diff --git a/packages/astro/src/cli/index.ts b/packages/astro/src/cli/index.ts index dce294487..fdab81aab 100644 --- a/packages/astro/src/cli/index.ts +++ b/packages/astro/src/cli/index.ts @@ -75,13 +75,18 @@ async function printVersion() { /** Determine which command the user requested */ function resolveCommand(flags: Arguments): CLICommand { const cmd = flags._[2] as string; - if (cmd === 'add') return 'add'; - if (cmd === 'sync') return 'sync'; - if (cmd === 'telemetry') return 'telemetry'; if (flags.version) return 'version'; - else if (flags.help) return 'help'; - const supportedCommands = new Set(['dev', 'build', 'preview', 'check', 'docs']); + const supportedCommands = new Set([ + 'add', + 'sync', + 'telemetry', + 'dev', + 'build', + 'preview', + 'check', + 'docs', + ]); if (supportedCommands.has(cmd)) { return cmd as CLICommand; } @@ -144,6 +149,16 @@ async function runCommand(cmd: string, flags: yargs.Arguments) { } case 'docs': { telemetry.record(event.eventCliSession(cmd)); + if (flags.help || flags.h) { + printHelp({ + commandName: 'astro docs', + tables: { + Flags: [['--help (-h)', 'See all available flags.']], + }, + description: `Launches the Astro Docs website directly from the terminal.`, + }); + return; + } return await openInBrowser('https://docs.astro.build/'); } case 'telemetry': { @@ -203,26 +218,29 @@ async function runCommand(cmd: string, flags: yargs.Arguments) { case 'build': { const { default: build } = await import('../core/build/index.js'); - return await build(settings, { ...flags, logging, telemetry, teardownCompiler: true }); + return await build(settings, { flags, logging, telemetry, teardownCompiler: true }); } case 'check': { - const ret = await check(settings, { logging }); + const ret = await check(settings, { logging, flags }); return process.exit(ret); } case 'sync': { const { syncCli } = await import('../core/sync/index.js'); - const ret = await syncCli(settings, { logging, fs }); + const ret = await syncCli(settings, { logging, fs, flags }); return process.exit(ret); } case 'preview': { const { default: preview } = await import('../core/preview/index.js'); - const server = await preview(settings, { logging, telemetry }); - return await server.closed(); // keep alive until the server is closed + const server = await preview(settings, { logging, telemetry, flags }); + if (server) { + return await server.closed(); // keep alive until the server is closed + } + return; } } diff --git a/packages/astro/src/cli/telemetry.ts b/packages/astro/src/cli/telemetry.ts index ee3ab47ff..a8ec1c174 100644 --- a/packages/astro/src/cli/telemetry.ts +++ b/packages/astro/src/cli/telemetry.ts @@ -10,7 +10,7 @@ export interface TelemetryOptions { export async function update(subcommand: string, { flags, telemetry }: TelemetryOptions) { const isValid = ['enable', 'disable', 'reset'].includes(subcommand); - if (flags.help || !isValid) { + if (flags.help || flags.h || !isValid) { msg.printHelp({ commandName: 'astro telemetry', usage: '[command]', diff --git a/packages/astro/src/core/build/index.ts b/packages/astro/src/core/build/index.ts index 4bb579eba..3d763d29c 100644 --- a/packages/astro/src/core/build/index.ts +++ b/packages/astro/src/core/build/index.ts @@ -21,6 +21,8 @@ import { collectPagesData } from './page-data.js'; import { staticBuild, viteBuild } from './static-build.js'; import { StaticBuildOptions } from './types.js'; import { getTimeStat } from './util.js'; +import { printHelp } from '../messages.js'; +import yargs from 'yargs-parser'; export interface BuildOptions { mode?: RuntimeMode; @@ -31,11 +33,27 @@ export interface BuildOptions { * building once, but may cause a performance hit if building multiple times in a row. */ teardownCompiler?: boolean; + flags?: yargs.Arguments; } /** `astro build` */ export default async function build(settings: AstroSettings, options: BuildOptions): Promise { applyPolyfill(); + if (options.flags?.help || options.flags?.h) { + printHelp({ + commandName: 'astro build', + usage: '[...flags]', + tables: { + Flags: [ + ['--drafts', `Include Markdown draft pages in the build.`], + ['--help (-h)', 'See all available flags.'], + ], + }, + description: `Builds your site for deployment.`, + }); + return; + } + const builder = new AstroBuilder(settings, options); await builder.run(); } diff --git a/packages/astro/src/core/dev/dev.ts b/packages/astro/src/core/dev/dev.ts index 378a7157e..32d5335ca 100644 --- a/packages/astro/src/core/dev/dev.ts +++ b/packages/astro/src/core/dev/dev.ts @@ -10,11 +10,13 @@ import { info, LogOptions, warn } from '../logger/core.js'; import * as msg from '../messages.js'; import { startContainer } from './container.js'; import { createContainerWithAutomaticRestart } from './restart.js'; +import { printHelp } from '../messages.js'; +import { cyan } from 'kleur/colors'; export interface DevOptions { configFlag: string | undefined; configFlagPath: string | undefined; - flags: yargs.Arguments | undefined; + flags?: yargs.Arguments; logging: LogOptions; telemetry: AstroTelemetry; handleConfigError: (error: Error) => void; @@ -32,7 +34,26 @@ export interface DevServer { export default async function dev( settings: AstroSettings, options: DevOptions -): Promise { +): Promise { + if (options.flags?.help || options.flags?.h) { + printHelp({ + commandName: 'astro dev', + usage: '[...flags]', + tables: { + Flags: [ + ['--port', `Specify which port to run on. Defaults to 3000.`], + ['--host', `Listen on all addresses, including LAN and public addresses.`], + ['--host ', `Expose on a network IP address at `], + ['--help (-h)', 'See all available flags.'], + ], + }, + description: `Check ${cyan( + 'https://docs.astro.build/en/reference/cli-reference/#astro-dev' + )} for more information.`, + }); + return; + } + const devStart = performance.now(); await options.telemetry.record([]); diff --git a/packages/astro/src/core/preview/index.ts b/packages/astro/src/core/preview/index.ts index 4488e5903..18555e7e4 100644 --- a/packages/astro/src/core/preview/index.ts +++ b/packages/astro/src/core/preview/index.ts @@ -6,17 +6,35 @@ import { runHookConfigDone, runHookConfigSetup } from '../../integrations/index. import type { LogOptions } from '../logger/core'; import createStaticPreviewServer from './static-preview-server.js'; import { getResolvedHostForHttpServer } from './util.js'; +import type { Arguments } from 'yargs-parser'; +import { printHelp } from '../messages.js'; +import { cyan } from 'kleur/colors'; interface PreviewOptions { logging: LogOptions; telemetry: AstroTelemetry; + flags?: Arguments; } /** The primary dev action */ export default async function preview( _settings: AstroSettings, - { logging }: PreviewOptions -): Promise { + { logging, flags }: PreviewOptions +): Promise { + if (flags?.help || flags?.h) { + printHelp({ + commandName: 'astro preview', + usage: '[...flags]', + tables: { + Flags: [['--help (-h)', 'See all available flags.']], + }, + description: `Starts a local server to serve your static dist/ directory. Check ${cyan( + 'https://docs.astro.build/en/reference/cli-reference/#astro-preview' + )} for more information.`, + }); + return; + } + const settings = await runHookConfigSetup({ settings: _settings, command: 'preview', diff --git a/packages/astro/src/core/sync/index.ts b/packages/astro/src/core/sync/index.ts index be8f84d2a..f52e4918e 100644 --- a/packages/astro/src/core/sync/index.ts +++ b/packages/astro/src/core/sync/index.ts @@ -11,13 +11,27 @@ import { getTimeStat } from '../build/util.js'; import { createVite } from '../create-vite.js'; import { AstroError, AstroErrorData } from '../errors/index.js'; import { info, LogOptions } from '../logger/core.js'; +import { printHelp } from '../messages.js'; +import { Arguments } from 'yargs-parser'; type ProcessExit = 0 | 1; export async function syncCli( settings: AstroSettings, - { logging, fs }: { logging: LogOptions; fs: typeof fsMod } + { logging, fs, flags }: { logging: LogOptions; fs: typeof fsMod; flags?: Arguments } ): Promise { + if (flags?.help || flags?.h) { + printHelp({ + commandName: 'astro sync', + usage: '[...flags]', + tables: { + Flags: [['--help (-h)', 'See all available flags.']], + }, + description: `Generates TypeScript types for all Astro modules.`, + }); + return 0; + } + const resolvedSettings = await runHookConfigSetup({ settings, logging,