@burger-api/cli 0.6.6

package/src/commands/create.ts

@@ -0,0 +1,229 @@
+/**
+ * Create Command
+ *
+ * This command helps users create a new Burger API project.
+ * It asks simple questions and sets up everything they need to get started.
+ *
+ * We use @clack/prompts for beautiful, user-friendly interactive prompts.
+ */
+
+import { Command } from 'commander';
+import * as clack from '@clack/prompts';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import type { CreateOptions } from '../types/index';
+import { createProject, installDependencies } from '../utils/templates';
+import {
+    success,
+    error as logError,
+    info,
+    newline,
+    header,
+    command,
+    highlight,
+} from '../utils/logger';
+
+/**
+ * Create the "create" command
+ * This is what runs when users type: burger-api create <projectName>
+ */
+/**
+ * Validate project name for filesystem compatibility
+ * @param name - Project name to validate
+ * @returns Error message if invalid, undefined if valid
+ */
+function validateProjectName(name: string): string | undefined {
+    if (!name) return 'Project name is required';
+    if (name.length > 100)
+        return 'Project name is too long (max 100 characters)';
+    if (/^[.-]/.test(name))
+        return 'Project name cannot start with a dot or dash';
+    if (/[<>:"/\\|?*\x00-\x1F]/.test(name)) {
+        return 'Project name contains invalid characters';
+    }
+    if (/\s/.test(name)) return 'Project name cannot contain spaces';
+    return undefined;
+}
+
+export const createCommand = new Command('create')
+    .description('Create a new Burger API project')
+    .argument('<project-name>', 'Name of your project')
+    .action(async (projectName: string) => {
+        // Start with a nice intro
+        clack.intro('Create a new BurgerAPI project');
+
+        try {
+            // Validate project name
+            const nameError = validateProjectName(projectName);
+            if (nameError) {
+                clack.outro('Invalid project name');
+                logError(nameError);
+                process.exit(1);
+            }
+
+            // Check if directory already exists
+            const targetDir = join(process.cwd(), projectName);
+            if (existsSync(targetDir)) {
+                clack.outro('Directory already exists!');
+                logError(`A directory named "${projectName}" already exists.`);
+                process.exit(1);
+            }
+
+            // Ask user questions to configure the project
+            const options = await askQuestions(projectName);
+
+            // User cancelled
+            if (clack.isCancel(options)) {
+                clack.outro('Operation cancelled');
+                process.exit(0);
+            }
+
+            // Show what we're about to create
+            info('Creating project with the following configuration:');
+            newline();
+            console.log(`  Name: ${projectName}`);
+            if (options.useApi) {
+                console.log(`  API Routes: ${options.apiDir || 'api'}`);
+            }
+            if (options.usePages) {
+                console.log(`  Page Routes: ${options.pageDir || 'pages'}`);
+            }
+            newline();
+
+            // Create the project
+            await createProject(targetDir, options);
+
+            // Install dependencies
+            await installDependencies(targetDir);
+
+            // Success! Show them what to do next
+            clack.outro('Project created successfully!');
+            newline();
+            header('Next Steps');
+            console.log(`  1. Navigate to your project:`);
+            command(`cd ${projectName}`);
+            newline();
+            console.log(`  2. Start the development server:`);
+            command('bun run dev');
+            newline();
+            console.log(`  3. Open your browser:`);
+            console.log(`     ${highlight('http://localhost:4000')}`);
+            newline();
+            console.log(`  4. Add middleware (optional):`);
+            command('burger-api add cors logger');
+            newline();
+            success('Happy coding!');
+        } catch (err) {
+            clack.outro('Failed to create project');
+            logError(err instanceof Error ? err.message : 'Unknown error');
+            process.exit(1);
+        }
+    });
+
+/**
+ * Ask user questions to configure their project
+ * Uses @clack/prompts for beautiful interactive prompts
+ *
+ * @param projectName - Name of the project
+ * @returns Configuration options from user answers
+ */
+async function askQuestions(projectName: string): Promise<CreateOptions> {
+    // Ask all questions in a nice flow
+    const answers = await clack.group(
+        {
+            // Question 1: Do you need API routes?
+            useApi: () =>
+                clack.confirm({
+                    message: 'Do you need API routes?',
+                    initialValue: true,
+                }),
+
+            // Question 2: API directory (only if they said yes to API)
+            apiDir: ({ results }) =>
+                results.useApi
+                    ? clack.text({
+                          message: 'API directory name:',
+                          initialValue: 'api',
+                          placeholder: 'api',
+                          validate: (value) => {
+                              if (!value)
+                                  return 'Please enter a directory name';
+                              if (value.includes(' '))
+                                  return 'Directory name cannot contain spaces';
+                          },
+                      })
+                    : Promise.resolve('api'),
+
+            // Question 3: API prefix (only if they said yes to API)
+            apiPrefix: ({ results }) =>
+                results.useApi
+                    ? clack.text({
+                          message: 'API route prefix:',
+                          initialValue: '/api',
+                          placeholder: '/api',
+                      })
+                    : Promise.resolve('/api'),
+
+            // Question 4: Debug mode (only if they said yes to API)
+            debug: ({ results }) =>
+                results.useApi
+                    ? clack.confirm({
+                          message: 'Enable debug mode?',
+                          initialValue: false,
+                      })
+                    : Promise.resolve(false),
+
+            // Question 5: Do you need Page routes?
+            usePages: () =>
+                clack.confirm({
+                    message: 'Do you need Page routes?',
+                    initialValue: false,
+                }),
+
+            // Question 6: Page directory (only if they said yes to Pages)
+            pageDir: ({ results }) =>
+                results.usePages
+                    ? clack.text({
+                          message: 'Page directory name:',
+                          initialValue: 'pages',
+                          placeholder: 'pages',
+                          validate: (value) => {
+                              if (!value)
+                                  return 'Please enter a directory name';
+                              if (value.includes(' '))
+                                  return 'Directory name cannot contain spaces';
+                          },
+                      })
+                    : Promise.resolve('pages'),
+
+            // Question 7: Page prefix (only if they said yes to Pages)
+            pagePrefix: ({ results }) =>
+                results.usePages
+                    ? clack.text({
+                          message: 'Page route prefix:',
+                          initialValue: '/',
+                          placeholder: '/',
+                      })
+                    : Promise.resolve('/'),
+        },
+        {
+            // Callback when user cancels (Ctrl+C)
+            onCancel: () => {
+                clack.cancel('Operation cancelled');
+                process.exit(0);
+            },
+        }
+    );
+
+    // Return the configuration
+    return {
+        name: projectName,
+        useApi: answers.useApi as boolean,
+        apiDir: answers.apiDir as string | undefined,
+        apiPrefix: answers.apiPrefix as string | undefined,
+        debug: answers.debug as boolean | undefined,
+        usePages: answers.usePages as boolean,
+        pageDir: answers.pageDir as string | undefined,
+        pagePrefix: answers.pagePrefix as string | undefined,
+    };
+}

package/src/commands/list.ts

@@ -0,0 +1,88 @@
+/**
+ * List Command
+ *
+ * Shows users all available middleware they can add to their project.
+ * Fetches the list from GitHub and displays it in a nice table format.
+ *
+ * Example: burger-api list
+ */
+
+import { Command } from 'commander';
+import { getMiddlewareList, getMiddlewareInfo } from '../utils/github';
+import {
+    header,
+    spinner,
+    error as logError,
+    table,
+    newline,
+    info,
+    dim,
+    command,
+} from '../utils/logger';
+
+/**
+ * Create the "list" command
+ * This shows all available middleware from the ecosystem
+ */
+export const listCommand = new Command('list')
+    .description('Show available middleware from the ecosystem')
+    .alias('ls') // Allow users to type "burger-api ls" too
+    .action(async () => {
+        // Show a spinner while fetching from GitHub
+        const spin = spinner('Fetching middleware list from GitHub...');
+
+        try {
+            // Get the list of middleware names
+            const middlewareNames = await getMiddlewareList();
+
+            // Fetch details for each middleware (in parallel for speed!)
+            const middlewareDetails = await Promise.all(
+                middlewareNames.map((name) =>
+                    getMiddlewareInfo(name).catch(() => ({
+                        name,
+                        description: 'No description available',
+                        path: '',
+                        files: [],
+                    }))
+                )
+            );
+
+            spin.stop('Found available middleware!');
+            newline();
+
+            // Display header
+            header('Available Middleware');
+
+            // Create table data
+            const tableData: string[][] = [
+                ['Name', 'Description'],
+                ...middlewareDetails.map((m) => [
+                    m.name,
+                    m.description.length > 60
+                        ? m.description.substring(0, 57) + '...'
+                        : m.description,
+                ]),
+            ];
+
+            // Show the table
+            table(tableData);
+            newline();
+
+            // Show usage instructions
+            info('To add middleware to your project, run:');
+            command('burger-api add <middleware-name>');
+            newline();
+            dim('Example: burger-api add cors logger rate-limiter');
+            newline();
+        } catch (err) {
+            spin.stop('Failed to fetch middleware list', true);
+            logError(
+                err instanceof Error
+                    ? err.message
+                    : 'Could not connect to GitHub'
+            );
+            newline();
+            info('Please check your internet connection and try again.');
+            process.exit(1);
+        }
+    });

package/src/commands/serve.ts

@@ -0,0 +1,100 @@
+/**
+ * Serve Command
+ *
+ * Runs a development server with hot reload (auto-restart on file changes).
+ * This is perfect for development - just edit your code and see changes instantly!
+ *
+ * Example: burger-api serve
+ * Example: burger-api serve --port 4000
+ */
+
+import { Command } from 'commander';
+import { existsSync } from 'fs';
+import {
+    success,
+    error as logError,
+    info,
+    newline,
+    highlight,
+    dim,
+} from '../utils/logger';
+
+/**
+ * Serve command options
+ */
+interface ServeCommandOptions {
+    port: string;
+    file: string;
+}
+
+/**
+ * Create the "serve" command
+ * Starts a development server with hot reload
+ */
+export const serveCommand = new Command('serve')
+    .description('Start development server with hot reload')
+    .option('-p, --port <port>', 'Port to run the server on', '4000')
+    .option('-f, --file <file>', 'Entry file to run', 'src/index.ts')
+    .action(async (options: ServeCommandOptions) => {
+        const file = options.file;
+        const port = options.port;
+
+        // Check if the entry file exists
+        if (!existsSync(file)) {
+            logError(`Entry file not found: ${file}`);
+            info('Make sure you are in the project directory.');
+            process.exit(1);
+        }
+
+        // Show startup message
+        newline();
+        info('Starting development server...');
+        newline();
+        success(`Server running on ${highlight(`http://localhost:${port}`)}`);
+        info('Press Ctrl+C to stop');
+        dim('File changes will automatically restart the server');
+        newline();
+
+        try {
+            // Run bun with --watch flag for hot reload
+            // We use --watch to automatically restart when files change
+            const proc = Bun.spawn(['bun', '--watch', file], {
+                stdout: 'inherit', // Show output in the terminal
+                stderr: 'inherit', // Show errors in the terminal
+                stdin: 'inherit', // Allow user input
+                env: {
+                    ...process.env,
+                    PORT: port, // Pass port as environment variable
+                },
+            });
+
+            // Handle Ctrl+C gracefully
+            process.on('SIGINT', () => {
+                newline();
+                info('Shutting down server...');
+                proc.kill();
+                process.exit(0);
+            });
+
+            // Handle Ctrl+Break on Windows
+            process.on('SIGBREAK', () => {
+                newline();
+                info('Shutting down server...');
+                proc.kill();
+                process.exit(0);
+            });
+
+            // Wait for the process to exit
+            const exitCode = await proc.exited;
+
+            if (exitCode !== 0) {
+                logError('Server stopped unexpectedly');
+                process.exit(exitCode);
+            }
+        } catch (err) {
+            logError(
+                err instanceof Error ? err.message : 'Failed to start server'
+            );
+            process.exit(1);
+        }
+    });

package/src/index.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env bun
+
+/**
+ * BurgerAPI CLI Tool
+ *
+ * This is the main entry point for the CLI.
+ * It sets up all the commands users can run.
+ *
+ * We use commander to handle command parsing and routing.
+ * This makes it easy to add new commands and provide helpful error messages.
+ */
+
+import { Command } from 'commander';
+import { createCommand } from './commands/create';
+import { addCommand } from './commands/add';
+import { listCommand } from './commands/list';
+import { buildCommand, buildExecutableCommand } from './commands/build';
+import { serveCommand } from './commands/serve';
+import { showBanner } from './utils/logger';
+
+/**
+ * Create the main CLI program
+ * This is what runs when someone types 'burger-api' in their terminal
+ */
+const program = new Command();
+
+// Set up basic information about our CLI
+program
+    .name('burger-api')
+    .description('Simple tool to work with BurgerAPI projects')
+    .version('0.6.6');
+
+// Add all our commands to the CLI
+// Each command is defined in its own file for better organization
+program.addCommand(createCommand); // Create new projects
+program.addCommand(addCommand); // Add middleware to projects
+program.addCommand(listCommand); // List available middleware
+program.addCommand(buildCommand); // Bundle to JS file
+program.addCommand(buildExecutableCommand); // Compile to executable
+program.addCommand(serveCommand); // Run development server
+
+// Show banner + help when no command is provided
+program.action(() => {
+    showBanner();
+    program.help();
+});
+
+// Override the help display to include banner
+program.configureOutput({
+    writeOut: (str) => {
+        process.stdout.write(str);
+    },
+    writeErr: (str) => {
+        process.stderr.write(str);
+    },
+});
+
+// Run the CLI - this parses the arguments the user typed
+program.parse();

package/src/types/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared TypeScript types for the CLI
+ *
+ * These types are used across different parts of the CLI
+ * to ensure type safety and good developer experience.
+ */
+
+/**
+ * Options for creating a new Burger API project
+ */
+export interface CreateOptions {
+    /** Name of the project */
+    name: string;
+    /** Whether to include API routes */
+    useApi: boolean;
+    /** Directory for API routes (e.g., 'api') */
+    apiDir?: string;
+    /** Prefix for API routes (e.g., '/api') */
+    apiPrefix?: string;
+    /** Enable debug mode */
+    debug?: boolean;
+    /** Whether to include Page routes */
+    usePages: boolean;
+    /** Directory for Page routes (e.g., 'pages') */
+    pageDir?: string;
+    /** Prefix for Page routes (e.g., '/') */
+    pagePrefix?: string;
+}
+
+/**
+ * Information about a middleware/feature from GitHub
+ */
+export interface MiddlewareInfo {
+    /** Name of the middleware (e.g., 'cors') */
+    name: string;
+    /** Short description of what it does */
+    description: string;
+    /** Path in the GitHub repo */
+    path: string;
+    /** Files that are part of this middleware */
+    files: string[];
+}
+
+/**
+ * GitHub API response for directory contents
+ */
+export interface GitHubFile {
+    name: string;
+    path: string;
+    type: 'file' | 'dir';
+    download_url?: string;
+    size: number;
+}