Improve cli output (#100)

* fix: update documentation and configuration for getting started guide

- Changed label in astro.config.mjs from 'Getting Started' to 'START HERE'
- Added new 'Getting Started' page content with introductory guide and navigation cards
- Improved onboarding flow for new users by providing clearer entry point and resources

* fix(docs): update getting-started guide link and rename trigger-and-monitor to run-flow

* fix: improve CLI output formatting and add outro messaging for better UX

- Corrected string formatting in createTaskLog for consistent output
- Enhanced flow name extraction with regex and fallback logic
- Added outro calls after successful and failed compilations for clearer guidance
- Included additional messaging in install commands to inform users about next steps
- Updated import statements to include missing modules and ensure proper functionality
- Refined user prompts and success/error messages for consistency and clarity

* docs: add changelog entry for minor 'pgflow' update and improve outro messaging

* chore: update install command to remove unused import and improve messaging

Author: jumski

.changeset/ninety-kings-battle.md

@@ -0,0 +1,5 @@
+---
+'pgflow': minor
+---
+
+Improve outro messaging

pkgs/cli/src/commands/compile/index.ts

@@ -1,6 +1,6 @@
 import { type Command } from 'commander';
 import chalk from 'chalk';
-import { intro, log, note } from '@clack/prompts';
+import { intro, log, note, outro } from '@clack/prompts';
 import path from 'path';
 import fs from 'fs';
 import { spawn } from 'child_process';
@@ -35,14 +35,18 @@ function formatCommand(command: string, args: string[]): string {
 /**
  * Creates a task log entry with a command and its output
  */
-function createTaskLog(command: string, args: string[], output: string): string {
+function createTaskLog(
+  command: string,
+  args: string[],
+  output: string
+): string {
   return [
-    chalk.bold("Command:"),
+    chalk.bold('Command:'),
     formatCommand(command, args),
-    "",
-    chalk.bold("Output:"),
-    output.trim() ? output.trim() : "(no output)",
-  ].join("\n");
+    '',
+    chalk.bold('Output:'),
+    output.trim() ? output.trim() : '(no output)',
+  ].join('\n');
 }
 
 export default (program: Command) => {
@@ -129,20 +133,27 @@ export default (program: Command) => {
           resolvedFlowPath,
           resolvedDenoJsonPath
         );
-        
+
         // Extract flow name from the first line of the SQL output using regex
         // Looking for pattern: SELECT pgflow.create_flow('flow_name', ...);
-        const flowNameMatch = compiledSql.match(/SELECT\s+pgflow\.create_flow\s*\(\s*'([^']+)'/i);
-        
+        const flowNameMatch = compiledSql.match(
+          /SELECT\s+pgflow\.create_flow\s*\(\s*'([^']+)'/i
+        );
+
         // Use extracted flow name or fallback to the file basename if extraction fails
         let flowName;
         if (flowNameMatch && flowNameMatch[1]) {
           flowName = flowNameMatch[1];
           log.info(`Extracted flow name: ${flowName}`);
         } else {
           // Fallback to file basename if regex doesn't match
-          flowName = path.basename(resolvedFlowPath, path.extname(resolvedFlowPath));
-          log.warn(`Could not extract flow name from SQL, using file basename: ${flowName}`);
+          flowName = path.basename(
+            resolvedFlowPath,
+            path.extname(resolvedFlowPath)
+          );
+          log.warn(
+            `Could not extract flow name from SQL, using file basename: ${flowName}`
+          );
         }
 
         // Create migration filename in the format: <timestamp>_create_<flow_name>_flow.sql
@@ -157,16 +168,34 @@ export default (program: Command) => {
           migrationFilePath
         );
         log.success(`Migration file created: ${relativeFilePath}`);
-        
+
+        // Display next steps with outro
+        outro(
+          [
+            chalk.bold('Flow compilation completed successfully!'),
+            '',
+            `- Run ${chalk.cyan('supabase migration up')} to apply the migration`,
+            '',
+            chalk.bold('Continue the setup:'),
+            chalk.blue.underline('https://pgflow.dev/getting-started/run-flow/')
+          ].join('\n')
+        );
       } catch (error) {
         log.error(
           `Compilation failed: ${
             error instanceof Error ? error.message : String(error)
           }`
         );
-        
-        note('For troubleshooting help, visit: https://pgflow.dev/getting-started/compile-to-sql/');
-        
+
+        outro(
+          [
+            chalk.bold('Compilation failed!'),
+            '',
+            chalk.bold('For troubleshooting help:'),
+            chalk.blue.underline('https://pgflow.dev/getting-started/compile-to-sql/')
+          ].join('\n')
+        );
+
         process.exit(1);
       }
     });
@@ -220,7 +249,7 @@ async function runDenoCompilation(
     deno.on('close', (code) => {
       // Always display the task log with command and output
       note(createTaskLog('deno', args, stdout));
-      
+
       if (code === 0) {
         if (stdout.trim().length === 0) {
           reject(new Error('Compilation produced no output'));
@@ -246,4 +275,4 @@ async function runDenoCompilation(
       );
     });
   });
-}
+}

pkgs/cli/src/commands/install/index.ts

@@ -1,5 +1,6 @@
 import { type Command } from 'commander';
-import { intro, log, note, group, cancel } from '@clack/prompts';
+import { intro, group, cancel, outro } from '@clack/prompts';
+import chalk from 'chalk';
 import { copyMigrations } from './copy-migrations.js';
 import { updateConfigToml } from './update-config-toml.js';
 import { updateEnvFile } from './update-env-file.js';
@@ -18,7 +19,8 @@ export default (program: Command) => {
       const results = await group(
         {
           // Step 1: Determine Supabase path
-          supabasePath: () => supabasePathPrompt({ supabasePath: options.supabasePath }),
+          supabasePath: () =>
+            supabasePathPrompt({ supabasePath: options.supabasePath }),
 
           // Step 2: Update config.toml
           configUpdate: async ({ results: { supabasePath } }) => {
@@ -72,40 +74,49 @@ export default (program: Command) => {
       }
 
       // Show completion message
-      if (migrations || configUpdate || envFile) {
-        log.success('pgflow setup completed successfully');
-
-        // Show next steps if changes were made
-        const nextSteps = [];
+      const outroMessages = [];
 
-        if (configUpdate || envFile) {
-          nextSteps.push(
-            '• Restart your Supabase instance for configuration changes to take effect'
-          );
-        }
+      // Always start with a bolded acknowledgement
+      if (migrations || configUpdate || envFile) {
+        outroMessages.push(chalk.bold('pgflow setup completed successfully!'));
+      } else {
+        outroMessages.push(
+          chalk.bold(
+            'pgflow is already properly configured - no changes needed!'
+          )
+        );
+      }
 
-        if (migrations) {
-          nextSteps.push('• Apply the migrations with: supabase migrations up');
-        }
+      // Add a newline after the acknowledgement
+      outroMessages.push('');
 
-        // Add documentation link
-        nextSteps.push(
-          '• For more information, visit: https://pgflow.dev/getting-started/install-pgflow/'
+      // Add specific next steps if changes were made
+      if (configUpdate || envFile) {
+        outroMessages.push(
+          `- Restart your Supabase instance for configuration changes to take effect`
         );
+      }
 
-        if (nextSteps.length > 0) {
-          note(nextSteps.join('\n'), 'Next steps');
-        }
-      } else {
-        log.success(
-          'pgflow is already properly configured - no changes needed'
+      if (migrations) {
+        outroMessages.push(
+          `- Apply the migrations with: ${chalk.cyan('supabase migrations up')}`
         );
+      }
 
-        // Still show documentation link even if no changes were made
-        note(
-          'For more information about pgflow, visit: https://pgflow.dev/getting-started/install-pgflow/',
-          'Documentation'
-        );
+      // Always add documentation link with consistent formatting
+      if (outroMessages.length > 2) {
+        // If we have specific steps, add another newline
+        outroMessages.push('');
       }
+
+      outroMessages.push(
+        chalk.bold('Continue the setup:'),
+        chalk.blue.underline(
+          'https://pgflow.dev/getting-started/compile-to-sql/'
+        )
+      );
+
+      // Single outro for all paths
+      outro(outroMessages.join('\n'));
     });
 };

pkgs/website/astro.config.mjs

@@ -78,7 +78,7 @@ export default defineConfig({
             id: 'pgflow',
             items: [
               {
-                label: 'Getting Started',
+                label: 'START HERE',
                 autogenerate: { directory: 'getting-started/' },
               },
               {

pkgs/website/src/content/docs/getting-started/index.mdx

@@ -0,0 +1,20 @@
+---
+title: Getting Started
+description: Getting started with pgflow
+sidebar:
+  order: 0
+---
+
+Welcome to pgflow! This guide will walk you through the essential steps to start using pgflow for your workflow automation needs.
+
+import { CardGrid, LinkCard } from '@astrojs/starlight/components';
+
+<CardGrid>
+  <LinkCard title="Install pgflow" href="/getting-started/install-pgflow/" description="Learn how to install and set up pgflow in your project"/>
+  <LinkCard title="Create Your First Flow" href="/getting-started/create-first-flow/" description="Define your first workflow using the pgflow DSL"/>
+  <LinkCard title="Compile to SQL" href="/getting-started/compile-to-sql/" description="Convert your TypeScript workflows to PostgreSQL"/>
+  <LinkCard title="Run your flow" href="/getting-started/run-flow/" description="Run your flows and track their execution"/>
+</CardGrid>
+
+Follow these guides in order to get a complete understanding of the pgflow workflow.
+