New CLI help reference for studio and db commands (#10390)

* feat: new, formatted astro db help

* feat: add "studio commands" section to cli

* chore: changeset

* Update packages/db/src/core/cli/print-help.ts

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

* Update .changeset/thirty-bags-live.md

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

---------

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

.changeset/thirty-bags-live.md

@@ -0,0 +1,6 @@
+---
+"astro": patch
+"@astrojs/db": patch
+---
+
+Adds `--help` reference for new db and studio CLI commands

packages/astro/src/cli/index.ts

@@ -39,6 +39,11 @@ async function printAstroHelp() {
 				['preferences', 'Configure user preferences.'],
 				['telemetry', 'Configure telemetry settings.'],
 			],
+			'Studio Commands': [
+				['login', 'Authenticate your machine with Astro Studio.'],
+				['logout', 'End your authenticated session with Astro Studio.'],
+				['link', 'Link this project directory to an Astro Studio project.'],
+			],
 			'Global Flags': [
 				['--config <path>', 'Specify your config file.'],
 				['--root <path>', 'Specify your project root folder.'],

packages/db/src/core/cli/index.ts

@@ -1,6 +1,7 @@
 import type { AstroConfig } from 'astro';
 import type { Arguments } from 'yargs-parser';
 import { resolveDbConfig } from '../load-file.js';
+import { printHelp } from './print-help.js';
 
 export async function cli({
 	flags,
@@ -53,30 +54,29 @@ export async function cli({
 			return await cmd();
 		}
 		default: {
-			if (command == null) {
-				console.error(`No command provided.
-
-${showHelp()}`);
-			} else {
-				console.error(`Unknown command: ${command}
-
-${showHelp()}`);
+			if (command != null) {
+				console.error(`Unknown command: ${command}`);
 			}
+			printHelp({
+				commandName: 'astro db',
+				usage: '[command] [...flags]',
+				headline: ' ',
+				tables: {
+					Commands: [
+						['push', 'Push table schema updates to Astro Studio.'],
+						['verify', 'Test schema updates /w Astro Studio (good for CI).'],
+						[
+							'astro db execute <file-path>',
+							'Execute a ts/js file using astro:db. Use --remote to connect to Studio.',
+						],
+						[
+							'astro db shell --query <sql-string>',
+							'Execute a SQL string. Use --remote to connect to Studio.',
+						],
+					],
+				},
+			});
 			return;
 		}
 	}
-
-	function showHelp() {
-		return `astro db <command>
-		
-Usage:
-
-astro login          Authenticate your machine with Astro Studio
-astro logout         End your authenticated session with Astro Studio
-astro link           Link this directory to an Astro Studio project
-
-astro db gen         Creates snapshot based on your schema
-astro db push        Pushes schema updates to Astro Studio
-astro db verify      Tests schema updates /w Astro Studio (good for CI)`;
-	}
 }

packages/db/src/core/cli/print-help.ts

@@ -0,0 +1,69 @@
+import { bgWhite, black, dim, bgGreen, green, bold } from 'kleur/colors';
+
+/**
+ * Uses implementation from Astro core
+ * @see https://github.com/withastro/astro/blob/main/packages/astro/src/core/messages.ts#L303
+ */
+export function printHelp({
+	commandName,
+	headline,
+	usage,
+	tables,
+	description,
+}: {
+	commandName: string;
+	headline?: string;
+	usage?: string;
+	tables?: Record<string, [command: string, help: string][]>;
+	description?: string;
+}) {
+	const linebreak = () => '';
+	const title = (label: string) => `  ${bgWhite(black(` ${label} `))}`;
+	const table = (rows: [string, string][], { padding }: { padding: number }) => {
+		const split = process.stdout.columns < 60;
+		let raw = '';
+
+		for (const row of rows) {
+			if (split) {
+				raw += `    ${row[0]}\n    `;
+			} else {
+				raw += `${`${row[0]}`.padStart(padding)}`;
+			}
+			raw += '  ' + dim(row[1]) + '\n';
+		}
+
+		return raw.slice(0, -1); // remove latest \n
+	};
+
+	let message = [];
+
+	if (headline) {
+		message.push(
+			linebreak(),
+			`  ${bgGreen(black(` ${commandName} `))} ${green(
+				`v${process.env.PACKAGE_VERSION ?? ''}`
+			)} ${headline}`
+		);
+	}
+
+	if (usage) {
+		message.push(linebreak(), `  ${green(commandName)} ${bold(usage)}`);
+	}
+
+	if (tables) {
+		function calculateTablePadding(rows: [string, string][]) {
+			return rows.reduce((val, [first]) => Math.max(val, first.length), 0) + 2;
+		}
+		const tableEntries = Object.entries(tables);
+		const padding = Math.max(...tableEntries.map(([, rows]) => calculateTablePadding(rows)));
+		for (const [tableTitle, tableRows] of tableEntries) {
+			message.push(linebreak(), title(tableTitle), table(tableRows, { padding }));
+		}
+	}
+
+	if (description) {
+		message.push(linebreak(), `${description}`);
+	}
+
+	console.log(message.join('\n') + '\n');
+}