refactor(cli): docs (#14602)

Author: florian-lefebvre

packages/astro/src/cli/docs/core/open-docs.ts

@@ -0,0 +1,59 @@
+import type { Logger } from '../../../core/logger/core.js';
+import { defineCommand } from '../../domain/command.js';
+import type { CommandExecutor, PlatformProvider } from '../definitions.js';
+import type { Platform } from '../domains/platform.js';
+
+interface Options {
+	url: string;
+	platformProvider: PlatformProvider;
+	logger: Logger;
+	commandExecutor: CommandExecutor;
+}
+
+function getExecInputForPlatform(
+	platform: Platform,
+): [command: string, args?: Array<string>] | null {
+	switch (platform) {
+		case 'android':
+		case 'linux':
+			return ['xdg-open'];
+		case 'darwin':
+			return ['open'];
+		case 'win32':
+			return ['cmd', ['/c', 'start']];
+		case 'gitpod':
+			return ['/ide/bin/remote-cli/gitpod-code', ['--openExternal']];
+		case 'aix':
+		case 'freebsd':
+		case 'haiku':
+		case 'openbsd':
+		case 'sunos':
+		case 'cygwin':
+		case 'netbsd':
+		default:
+			return null;
+	}
+}
+
+export const openDocsCommand = defineCommand({
+	help: {
+		commandName: 'astro docs',
+		tables: {
+			Flags: [['--help (-h)', 'See all available flags.']],
+		},
+		description: `Launches the Astro Docs website directly from the terminal.`,
+	},
+	async run({ url, platformProvider, logger, commandExecutor }: Options) {
+		const platform = platformProvider.get();
+		const input = getExecInputForPlatform(platform);
+		if (!input) {
+			logger.error(
+				'SKIP_FORMAT',
+				`It looks like your platform ("${platform}") isn't supported!\nTo view Astro's docs, please visit ${url}`,
+			);
+			return;
+		}
+		const [command, args = []] = input;
+		await commandExecutor.execute(command, [...args, encodeURI(url)]);
+	},
+});

packages/astro/src/cli/docs/definitions.ts

@@ -0,0 +1,16 @@
+import type { Platform } from './domains/platform.js';
+
+export interface PlatformProvider {
+	get: () => Platform;
+}
+
+export interface CommandExecutor {
+	execute: (
+		command: string,
+		args?: Array<string>,
+		options?: {
+			cwd?: string;
+			env: Record<string, string | undefined>;
+		},
+	) => Promise<{ stdout: string }>;
+}

packages/astro/src/cli/docs/domains/platform.ts

@@ -0,0 +1 @@
+export type Platform = NodeJS.Platform | 'gitpod';

packages/astro/src/cli/docs/index.ts

@@ -0,0 +1,10 @@
+import type { PlatformProvider } from '../definitions.js';
+
+export function createProcessPlatformProvider(): PlatformProvider {
+	const platform = Boolean(process.env.GITPOD_REPO_ROOT) ? 'gitpod' : process.platform;
+	return {
+		get() {
+			return platform;
+		},
+	};
+}

packages/astro/src/cli/docs/infra/process-platform-provider.ts

@@ -0,0 +1,31 @@
+import { NonZeroExitError, x } from 'tinyexec';
+import type { CommandExecutor } from '../definitions.js';
+
+export function createTinyexecCommandExecutor(): CommandExecutor {
+	return {
+		async execute(command, args, options) {
+			return await x(command, args, {
+				throwOnError: true,
+				nodeOptions: {
+					cwd: options?.cwd,
+					env: options?.env,
+				},
+			}).then(
+				(o) => o,
+				(e) => {
+					if (e instanceof NonZeroExitError) {
+						const fullCommand = args?.length
+							? `${command} ${args.map((a) => (a.includes(' ') ? `"${a}"` : a)).join(' ')}`
+							: command;
+						const message = `The command \`${fullCommand}\` exited with code ${e.exitCode}`;
+						const newError = new Error(message, e.cause ? { cause: e.cause } : undefined);
+						(newError as any).stderr = e.output?.stderr;
+						(newError as any).stdout = e.output?.stdout;
+						throw newError;
+					}
+					throw e;
+				},
+			);
+		},
+	};
+}

packages/astro/src/cli/docs/infra/tinyexec-command-executor.ts

@@ -2,6 +2,7 @@ import { NonZeroExitError, type Options, x } from 'tinyexec';
 
 /**
  * Improve tinyexec error logging and set `throwOnError` to `true` by default
+ * @deprecated use CommandExecutor instead
  */
 export function exec(command: string, args?: string[], options?: Partial<Options>) {
 	return x(command, args, {

packages/astro/src/cli/docs/open.ts

@@ -102,13 +102,29 @@ async function runCommand(cmd: string, flags: yargs.Arguments) {
 				import('./create-key/infra/crypto-key-generator.js'),
 				import('./create-key/core/create-key.js'),
 			]);
+
 			const keyGenerator = createCryptoKeyGenerator();
 			return await runner.run(createKeyCommand, { logger, keyGenerator });
 		}
 		case 'docs': {
-			const { docs } = await import('./docs/index.js');
-			await docs({ flags });
-			return;
+			const [
+				{ createTinyexecCommandExecutor },
+				{ createProcessPlatformProvider },
+				{ openDocsCommand },
+			] = await Promise.all([
+				import('./docs/infra/tinyexec-command-executor.js'),
+				import('./docs/infra/process-platform-provider.js'),
+				import('./docs/core/open-docs.js'),
+			]);
+			const commandExecutor = createTinyexecCommandExecutor();
+			const platformProvider = createProcessPlatformProvider();
+
+			return await runner.run(openDocsCommand, {
+				url: 'https://docs.astro.build/',
+				logger,
+				commandExecutor,
+				platformProvider,
+			});
 		}
 		case 'telemetry': {
 			// Do not track session start, since the user may be trying to enable,

packages/astro/src/cli/exec.ts

@@ -1,9 +1,10 @@
 import type { AstroVersionProvider } from '../definitions.js';
 
 export function createBuildTimeAstroVersionProvider(): AstroVersionProvider {
+	const version = process.env.PACKAGE_VERSION ?? '';
 	return {
 		getVersion() {
-			return process.env.PACKAGE_VERSION ?? '';
+			return version;
 		},
 	};
 }