@burger-api/cli 0.9.1 → 0.9.4

package/CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to the Burger API CLI will be documented in this file.
 
-## Version 0.9.0 - (March 15, 2026)
+## Version 0.9.3 - (March 17, 2026)
 
 -   ✨ **Create** – New projects get a config file (`burger.config.ts`) from
     your answers; the build uses this config when present.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@burger-api/cli",
-  "version": "0.9.1",
+  "version": "0.9.4",
   "description": "Simple command-line tool for Burger API projects",
   "module": "src/index.ts",
   "type": "module",
@@ -20,10 +20,10 @@
     "dev": "bun run src/index.ts",
     "test": "bun test --timeout 30000 ./test",
     "test:build": "bun test test/scanner.test.ts test/virtual-entry.test.ts test/entry-options.test.ts test/build-preserve-options.test.ts",
-    "build:win": "bun build ./src/index.ts --compile --target bun-windows-x64 --outfile dist/burger-api.exe --minify",
-    "build:linux": "bun build ./src/index.ts --compile --target bun-linux-x64 --outfile dist/burger-api-linux --minify",
-    "build:mac": "bun build ./src/index.ts --compile --target bun-darwin-arm64 --outfile dist/burger-api-mac --minify",
-    "build:mac-intel": "bun build ./src/index.ts --compile --target bun-darwin-x64 --outfile dist/burger-api-mac-intel --minify",
+    "build:win": "bun run scripts/build-executable.ts win",
+    "build:linux": "bun run scripts/build-executable.ts linux",
+    "build:mac": "bun run scripts/build-executable.ts mac",
+    "build:mac-intel": "bun run scripts/build-executable.ts mac-intel",
     "build:all": "bun run build:win && bun run build:linux && bun run build:mac && bun run build:mac-intel"
   },
   "dependencies": {

package/src/commands/add.ts

@@ -69,7 +69,7 @@ export const addCommand = new Command('add')
         for (const name of middlewareNames) {
             try {
                 // Check if it exists on GitHub
-                const spin = spinner(`Checking ${name}...`);
+                let spin = spinner(`Checking ${name}...`);
 
                 let exists;
                 try {
@@ -106,6 +106,7 @@ export const addCommand = new Command('add')
                         results.skipped.push(name);
                         continue;
                     }
+                    spin = spinner(`Downloading ${name}...`);
                 }
 
                 // Download the middleware

package/src/commands/build.ts

@@ -11,6 +11,7 @@
 import { Command } from 'commander';
 import { existsSync } from 'fs';
 import { dirname, resolve } from 'path';
+import type { Spinner } from '../utils/logger';
 import {
     spinner,
     success,
@@ -20,9 +21,51 @@ import {
     formatSize,
     dim,
 } from '../utils/logger';
-import { runVirtualEntryBuild } from '../utils/build/pipeline';
+import {
+    runVirtualEntryBuild,
+    type VirtualBuildResult,
+} from '../utils/build/pipeline';
 import { getProjectName } from '../utils/build/project';
 
+function ensureEntryFileExists(cwd: string, file: string): void {
+    const entryPath = resolve(cwd, file);
+    if (!existsSync(entryPath)) {
+        logError(`Entry file not found: ${file}`);
+        info('Make sure you are in the project directory.');
+        process.exit(1);
+    }
+}
+
+async function runBuildWithSpinner(params: {
+    file: string;
+    cwd: string;
+    spinMessage: string;
+    failMessage: string;
+    buildOptions: Parameters<typeof runVirtualEntryBuild>[0];
+    onBeforeBuild?: (spin: Spinner) => void;
+    onSuccess: (result: VirtualBuildResult, spin: Spinner) => void;
+}): Promise<void> {
+    ensureEntryFileExists(params.cwd, params.file);
+    const spin = spinner(params.spinMessage);
+    try {
+        info('Build-time route discovery enabled.');
+        params.onBeforeBuild?.(spin);
+        const result = await runVirtualEntryBuild(params.buildOptions);
+        if (!result.success) {
+            spin.stop(params.failMessage, true);
+            logError(
+                'Bun.build failed. Check that api/page directories and route files are valid.'
+            );
+            process.exit(1);
+        }
+        params.onSuccess(result, spin);
+    } catch (err) {
+        spin.stop(params.failMessage, true);
+        logError(err instanceof Error ? err.message : 'Unknown error');
+        process.exit(1);
+    }
+}
+
 /**
  * Options for the `build` command.
  */
@@ -73,58 +116,39 @@ export const buildCommand = new Command('build')
     .option('--target <env>', 'Target environment (default: bun)')
     .action(async (file: string, options: BuildCommandOptions) => {
         const cwd = process.cwd();
-        const entryPath = resolve(cwd, file);
-        if (!existsSync(entryPath)) {
-            logError(`Entry file not found: ${file}`);
-            info('Make sure you are in the project directory.');
-            process.exit(1);
-        }
-
-        const spin = spinner('Building project...');
-
-        try {
-            info('Build-time route discovery enabled.');
-
-            const { success: ok, hasPages } = await runVirtualEntryBuild({
+        await runBuildWithSpinner({
+            file,
+            cwd,
+            spinMessage: 'Building project...',
+            failMessage: 'Build failed',
+            buildOptions: {
                 cwd,
                 entryFile: file,
                 outfile: options.outfile,
                 target: options.target || 'bun',
                 minify: options.minify,
                 sourcemap: options.sourcemap,
-            });
-
-            if (!ok) {
-                spin.stop('Build failed', true);
-                logError(
-                    'Bun.build failed. Check that api/page directories and route files are valid.'
-                );
-                process.exit(1);
-            }
-
-            const size = Bun.file(options.outfile).size;
-            const bundleDir = dirname(options.outfile);
-
-            spin.stop('Build completed successfully!');
-            newline();
-            success(`Bundle:  ${options.outfile}  (${formatSize(size)})`);
-            newline();
-            if (hasPages) {
-                info(`Pages and assets are in: ${bundleDir}/`);
-                dim(
-                    'Deploy the entire directory — HTML pages depend on their chunks.'
-                );
-                dim(`Run: bun ${options.outfile}`);
-            } else {
-                info('API-only bundle — self-contained single file.');
-                dim(`Run anywhere: bun ${options.outfile}`);
-            }
-            newline();
-        } catch (err) {
-            spin.stop('Build failed', true);
-            logError(err instanceof Error ? err.message : 'Unknown error');
-            process.exit(1);
-        }
+            },
+            onSuccess: (result, spin) => {
+                const size = Bun.file(options.outfile).size;
+                const bundleDir = dirname(options.outfile);
+                spin.stop('Build completed successfully!');
+                newline();
+                success(`Bundle:  ${options.outfile}  (${formatSize(size)})`);
+                newline();
+                if (result.hasPages) {
+                    info(`Pages and assets are in: ${bundleDir}/`);
+                    dim(
+                        'Deploy the entire directory — HTML pages depend on their chunks.'
+                    );
+                    dim(`Run: bun ${options.outfile}`);
+                } else {
+                    info('API-only bundle — self-contained single file.');
+                    dim(`Run anywhere: bun ${options.outfile}`);
+                }
+                newline();
+            },
+        });
     });
 
 /**
@@ -151,13 +175,6 @@ export const buildExecutableCommand = new Command('build:exec')
     .option('--no-bytecode', 'Disable bytecode compilation')
     .action(async (file: string, options: BuildExecutableOptions) => {
         const cwd = process.cwd();
-        const entryPath = resolve(cwd, file);
-        if (!existsSync(entryPath)) {
-            logError(`Entry file not found: ${file}`);
-            info('Make sure you are in the project directory.');
-            process.exit(1);
-        }
-
         let outfile = options.outfile;
         if (!outfile) {
             const projectName = getProjectName(cwd);
@@ -168,14 +185,14 @@ export const buildExecutableCommand = new Command('build:exec')
                 ? `.build/executable/${projectName}.exe`
                 : `.build/executable/${projectName}`;
         }
-
-        const spin = spinner('Compiling to executable...');
-
-        try {
-            info('Build-time route discovery enabled.');
-            spin.update('Compiling... (this may take a minute)');
-
-            const { success: ok, outputs } = await runVirtualEntryBuild({
+        const outfileFinal = outfile;
+
+        await runBuildWithSpinner({
+            file,
+            cwd,
+            spinMessage: 'Compiling to executable...',
+            failMessage: 'Compilation failed',
+            buildOptions: {
                 cwd,
                 entryFile: file,
                 outfile,
@@ -183,42 +200,32 @@ export const buildExecutableCommand = new Command('build:exec')
                 minify: options.minify,
                 bytecode: options.bytecode !== false,
                 compile: true,
-            });
-
-            if (!ok) {
-                spin.stop('Compilation failed', true);
-                logError(
-                    'Bun.build failed. Check that api/page directories and route files are valid.'
+            },
+            onBeforeBuild: (spin) =>
+                spin.update('Compiling... (this may take a minute)'),
+            onSuccess: (result, spin) => {
+                const size = existsSync(outfileFinal)
+                    ? Bun.file(outfileFinal).size
+                    : (result.outputs[0]?.size ?? 0);
+                spin.stop('Compilation completed successfully!');
+                newline();
+                success(`Executable: ${outfileFinal}`);
+                if (size > 0) info(`Size: ${formatSize(size)}`);
+                newline();
+                info(
+                    'Standalone binary — copy it anywhere, no Bun required on the target.'
                 );
-                process.exit(1);
-            }
-
-            const size = existsSync(outfile)
-                ? Bun.file(outfile).size
-                : (outputs[0]?.size ?? 0);
-
-            spin.stop('Compilation completed successfully!');
-            newline();
-            success(`Executable: ${outfile}`);
-            if (size > 0) info(`Size: ${formatSize(size)}`);
-            newline();
-            info(
-                'Standalone binary — copy it anywhere, no Bun required on the target.'
-            );
-            dim(
-                'All routes, pages, and assets are embedded inside the binary.'
-            );
-            newline();
-            if (process.platform !== 'win32') {
-                dim(`Make executable: chmod +x ${outfile}`);
-                dim(`Run: ./${outfile}`);
-            } else {
-                dim(`Run: ${outfile}`);
-            }
-            newline();
-        } catch (err) {
-            spin.stop('Compilation failed', true);
-            logError(err instanceof Error ? err.message : 'Unknown error');
-            process.exit(1);
-        }
+                dim(
+                    'All routes, pages, and assets are embedded inside the binary.'
+                );
+                newline();
+                if (process.platform !== 'win32') {
+                    dim(`Make executable: chmod +x ${outfileFinal}`);
+                    dim(`Run: ./${outfileFinal}`);
+                } else {
+                    dim(`Run: ${outfileFinal}`);
+                }
+                newline();
+            },
+        });
     });

package/src/commands/create.ts

@@ -10,7 +10,7 @@
 import { Command } from 'commander';
 import * as clack from '@clack/prompts';
 import { existsSync } from 'fs';
-import { join } from 'path';
+import { isAbsolute, join, relative, resolve } from 'path';
 import type { CreateOptions } from '../types/index';
 import { createProject, installDependencies } from '../utils/templates';
 import {
@@ -45,6 +45,26 @@ function validateProjectName(name: string): string | undefined {
     return undefined;
 }
 
+/**
+ * Ensure directory name (apiDir/pageDir) resolves under targetDir/src to prevent path traversal.
+ */
+function validateDirUnderSrc(
+    targetDir: string,
+    dirName: string,
+    label: string
+): string | undefined {
+    if (!dirName || dirName.includes('..')) {
+        return `${label} cannot be empty or contain '..'`;
+    }
+    const srcRoot = resolve(targetDir, 'src');
+    const resolved = resolve(targetDir, 'src', dirName);
+    const rel = relative(srcRoot, resolved);
+    if (rel.startsWith('..') || isAbsolute(rel)) {
+        return `${label} must resolve inside the project's src directory`;
+    }
+    return undefined;
+}
+
 export const createCommand = new Command('create')
     .description('Create a new Burger API project')
     .argument('<project-name>', 'Name of your project')
@@ -78,6 +98,32 @@ export const createCommand = new Command('create')
                 process.exit(0);
             }
 
+            // Validate apiDir/pageDir stay under targetDir/src (prevent path traversal)
+            if (options.useApi) {
+                const apiDirError = validateDirUnderSrc(
+                    targetDir,
+                    options.apiDir || 'api',
+                    'API directory'
+                );
+                if (apiDirError) {
+                    clack.outro('Invalid configuration');
+                    logError(apiDirError);
+                    process.exit(1);
+                }
+            }
+            if (options.usePages) {
+                const pageDirError = validateDirUnderSrc(
+                    targetDir,
+                    options.pageDir || 'pages',
+                    'Page directory'
+                );
+                if (pageDirError) {
+                    clack.outro('Invalid configuration');
+                    logError(pageDirError);
+                    process.exit(1);
+                }
+            }
+
             // Show what we're about to create
             info('Creating project with the following configuration:');
             newline();
@@ -154,6 +200,8 @@ async function askQuestions(projectName: string): Promise<CreateOptions> {
                                   return 'Please enter a directory name';
                               if (value.includes(' '))
                                   return 'Directory name cannot contain spaces';
+                              if (value.includes('..'))
+                                  return 'Directory name cannot contain ..';
                           },
                       })
                     : Promise.resolve('api'),
@@ -196,6 +244,8 @@ async function askQuestions(projectName: string): Promise<CreateOptions> {
                                   return 'Please enter a directory name';
                               if (value.includes(' '))
                                   return 'Directory name cannot contain spaces';
+                              if (value.includes('..'))
+                                  return 'Directory name cannot contain ..';
                           },
                       })
                     : Promise.resolve('pages'),

package/src/commands/list.ts

@@ -11,7 +11,7 @@ import { Command } from 'commander';
 import { getMiddlewareList, getMiddlewareInfo } from '../utils/github';
 import {
     header,
-    spinner,
+    withSpinner,
     error as logError,
     table,
     newline,
@@ -28,54 +28,49 @@ 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();
+            await withSpinner(
+                'Fetching middleware list from GitHub...',
+                async (spin) => {
+                    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: [],
-                    }))
-                )
-            );
+                    const middlewareDetails = await Promise.all(
+                        middlewareNames.map((name) =>
+                            getMiddlewareInfo(name).catch(() => ({
+                                name,
+                                description: 'No description available',
+                                path: '',
+                                files: [],
+                            }))
+                        )
+                    );
 
-            spin.stop('Found available middleware!');
-            newline();
+                    spin.stop('Found available middleware!');
+                    newline();
 
-            // Display header
-            header('Available Middleware');
+                    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,
-                ]),
-            ];
+                    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();
+                    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();
+                    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

package/src/index.ts

@@ -20,11 +20,18 @@ import { buildCommand, buildExecutableCommand } from './commands/build';
 import { serveCommand } from './commands/serve';
 import { showBanner } from './utils/logger';
 
+/** Injected at build time when compiling to executable (--define CLI_VERSION). */
+declare const CLI_VERSION: string | undefined;
+
 /**
  * Read CLI version from package.json (single source of truth for publish).
+ * When running as compiled binary, version is injected at build time via CLI_VERSION.
  * @returns The version of the CLI.
  */
 function getVersion(): string {
+    if (typeof CLI_VERSION !== 'undefined') {
+        return CLI_VERSION;
+    }
     try {
         const pkgPath = join(import.meta.dir, '..', 'package.json');
         const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as {
@@ -73,5 +80,25 @@ program.configureOutput({
     },
 });
 
+// Use exit code 2 for usage errors (invalid options/args) per CLI guidelines
+const USAGE_ERROR_CODES = [
+    'commander.unknownOption',
+    'commander.unknownArgument',
+    'commander.missingMandatoryOptionValue',
+    'commander.invalidOptionArgument',
+    'commander.invalidArgument',
+];
+program.exitOverride((err) => {
+    const errorCode = (err as { code?: string }).code;
+    const code =
+        err.exitCode === 0
+            ? 0
+            : typeof errorCode === 'string' &&
+                USAGE_ERROR_CODES.includes(errorCode)
+              ? 2
+              : 1;
+    process.exit(code);
+});
+
 // Run the CLI - this parses the arguments the user typed
 program.parse();

package/src/utils/build/bun.ts

@@ -0,0 +1,134 @@
+import { resolve } from 'path';
+
+function formatBunBuildLogs(logs: unknown): string {
+    if (!Array.isArray(logs) || logs.length === 0) {
+        return '';
+    }
+
+    const messages: string[] = [];
+    for (const item of logs) {
+        if (!item || typeof item !== 'object') continue;
+
+        const log = item as {
+            level?: string;
+            message?: string;
+            text?: string;
+            name?: string;
+            position?: { file?: string; line?: number; column?: number };
+        };
+        const text =
+            (typeof log.message === 'string' && log.message) ||
+            (typeof log.text === 'string' && log.text) ||
+            (typeof log.name === 'string' && log.name) ||
+            '';
+        if (!text) continue;
+
+        const level =
+            typeof log.level === 'string' ? log.level.toUpperCase() : 'ERROR';
+        const file = log.position?.file ? `${log.position.file}` : '';
+        const line =
+            typeof log.position?.line === 'number'
+                ? `:${log.position.line}`
+                : '';
+        const column =
+            typeof log.position?.column === 'number'
+                ? `:${log.position.column}`
+                : '';
+        const location = file ? ` (${file}${line}${column})` : '';
+        messages.push(`- [${level}] ${text}${location}`);
+    }
+    return messages.join('\n');
+}
+
+function extractBunBuildDetails(err: unknown): string {
+    if (!err || typeof err !== 'object') {
+        return '';
+    }
+
+    const anyErr = err as {
+        logs?: unknown;
+        errors?: unknown;
+        cause?: { logs?: unknown; errors?: unknown };
+    };
+    const candidates = [
+        anyErr.logs,
+        anyErr.errors,
+        anyErr.cause?.logs,
+        anyErr.cause?.errors,
+    ];
+
+    for (const candidate of candidates) {
+        const detail = formatBunBuildLogs(candidate);
+        if (detail) return detail;
+    }
+    return '';
+}
+
+export function createBunBuildOptions(options: {
+    entryPath: string;
+    outDir: string;
+    cwd: string;
+    outfile: string;
+    target?: string;
+    minify?: boolean;
+    sourcemap?: string;
+    compile?: boolean;
+    bytecode?: boolean;
+}): Parameters<typeof Bun.build>[0] {
+    const buildOptions: Parameters<typeof Bun.build>[0] = {
+        entrypoints: [options.entryPath],
+        outdir: options.outDir,
+        target: (options.target as 'bun') || 'bun',
+        minify: options.minify ?? false,
+        splitting: false,
+        sourcemap:
+            options.sourcemap === undefined
+                ? undefined
+                : (options.sourcemap as 'none' | 'linked' | 'inline' | 'external'),
+    };
+
+    const ext = buildOptions as unknown as Record<string, unknown>;
+    ext.naming = {
+        chunk: '[name]-[hash].[ext]',
+        asset: '[name]-[hash].[ext]',
+    };
+
+    if (options.compile) {
+        ext.compile = {
+            outfile: resolve(options.cwd, options.outfile),
+            ...(options.target && { target: options.target }),
+        };
+        if (options.bytecode !== false) {
+            ext.bytecode = true;
+        }
+        delete ext.outdir;
+    }
+
+    return buildOptions;
+}
+
+export async function runBunBuildOrThrow(
+    buildOptions: Parameters<typeof Bun.build>[0]
+): Promise<Awaited<ReturnType<typeof Bun.build>>> {
+    let result: Awaited<ReturnType<typeof Bun.build>>;
+    try {
+        result = await Bun.build(buildOptions);
+    } catch (err) {
+        const detail = extractBunBuildDetails(err);
+        const message = err instanceof Error ? err.message : 'Bun.build failed.';
+        if (detail) {
+            throw new Error(`${message}\n${detail}`);
+        }
+        throw new Error(message);
+    }
+
+    if (!result.success) {
+        const detail = formatBunBuildLogs((result as { logs?: unknown }).logs);
+        if (detail) {
+            throw new Error(`Bun.build failed.\n${detail}`);
+        }
+        throw new Error('Bun.build failed.');
+    }
+
+    return result;
+}

package/src/utils/build/entry.ts

@@ -0,0 +1,74 @@
+import { dirname, resolve } from 'path';
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from 'fs';
+
+export function prepareVirtualEntry(options: {
+    cwd: string;
+    outfile: string;
+    pageDir: string;
+    source: string;
+    hasPages: boolean;
+}): { outDir: string; virtualSourcePath: string; virtualPath: string } {
+    const outDir = resolve(options.cwd, dirname(options.outfile));
+    mkdirSync(outDir, { recursive: true });
+
+    const virtualEntryDir = options.hasPages
+        ? resolve(options.cwd, options.pageDir)
+        : outDir;
+    mkdirSync(virtualEntryDir, { recursive: true });
+
+    const virtualSourcePath = resolve(virtualEntryDir, '__burger_build_entry__.ts');
+    const virtualPath = virtualSourcePath.split('\\').join('/');
+    writeFileSync(virtualSourcePath, options.source, 'utf-8');
+
+    return { outDir, virtualSourcePath, virtualPath };
+}
+
+export function cleanupVirtualEntry(virtualSourcePath: string): void {
+    if (existsSync(virtualSourcePath)) {
+        unlinkSync(virtualSourcePath);
+    }
+}
+
+export async function finalizeBuildOutputs(options: {
+    result: Awaited<ReturnType<typeof Bun.build>>;
+    cwd: string;
+    outfile: string;
+    outDir: string;
+    compile?: boolean;
+}): Promise<{ path: string; size: number }[]> {
+    const desiredOut = resolve(options.cwd, options.outfile);
+    const outputs: { path: string; size: number }[] = [];
+
+    if (!options.result.outputs?.length) {
+        return outputs;
+    }
+
+    const first = options.result.outputs[0] as Blob & { path?: string };
+    const outPath = first.path ? resolve(first.path) : undefined;
+
+    const entryArtifacts = new Set<string>([
+        resolve(options.outDir, '__burger_build_entry__.js'),
+    ]);
+    if (outPath?.endsWith('__burger_build_entry__.js')) {
+        entryArtifacts.add(outPath);
+    }
+
+    if (!options.compile && outPath && outPath !== desiredOut) {
+        const blob = first as Blob;
+        await Bun.write(desiredOut, blob);
+        outputs.push({ path: desiredOut, size: blob.size });
+    } else {
+        outputs.push({
+            path: outPath ?? desiredOut,
+            size: (first as Blob).size ?? 0,
+        });
+    }
+
+    for (const entryArtifact of entryArtifacts) {
+        if (entryArtifact !== desiredOut && existsSync(entryArtifact)) {
+            unlinkSync(entryArtifact);
+        }
+    }
+
+    return outputs;
+}

package/src/utils/build/pipeline.ts

@@ -0,0 +1,90 @@
+import { resolveBuildConfig } from '../config';
+import { scanApiRoutes, scanPageRoutes } from '../scanner';
+import { generateVirtualEntrySource } from '../virtual-entry';
+import { createBunBuildOptions, runBunBuildOrThrow } from './bun';
+import {
+    cleanupVirtualEntry,
+    finalizeBuildOutputs,
+    prepareVirtualEntry,
+} from './entry';
+import {
+    cleanupEntryOptionsModule,
+    prepareEntryOptionsModule,
+} from '../entry-options';
+
+export interface VirtualBuildResult {
+    success: boolean;
+    hasPages: boolean;
+    outputs: { path: string; size: number }[];
+}
+
+export async function runVirtualEntryBuild(options: {
+    cwd: string;
+    entryFile: string;
+    outfile: string;
+    target?: string;
+    minify?: boolean;
+    sourcemap?: string;
+    compile?: boolean;
+    bytecode?: boolean;
+}): Promise<VirtualBuildResult> {
+    const config = await resolveBuildConfig(options.cwd);
+    const entryOptions = prepareEntryOptionsModule({
+        cwd: options.cwd,
+        entryFile: options.entryFile,
+    });
+
+    const [apiEntries, pageEntries] = await Promise.all([
+        scanApiRoutes(options.cwd, config.apiDir, config.apiPrefix),
+        scanPageRoutes(options.cwd, config.pageDir, config.pagePrefix),
+    ]);
+
+    if (apiEntries.length === 0 && pageEntries.length === 0) {
+        throw new Error(
+            `No routes found. Ensure ${config.apiDir} or ${config.pageDir} ` +
+                `exist and contain route.ts files or page files.`
+        );
+    }
+
+    const source = generateVirtualEntrySource(
+        config,
+        apiEntries,
+        pageEntries,
+        entryOptions.importPath
+    );
+    const hasPages = pageEntries.length > 0;
+    const { outDir, virtualPath, virtualSourcePath } = prepareVirtualEntry({
+        cwd: options.cwd,
+        outfile: options.outfile,
+        pageDir: config.pageDir,
+        source,
+        hasPages,
+    });
+
+    const buildOptions = createBunBuildOptions({
+        entryPath: virtualPath,
+        outDir,
+        cwd: options.cwd,
+        outfile: options.outfile,
+        target: options.target,
+        minify: options.minify,
+        sourcemap: options.sourcemap,
+        compile: options.compile,
+        bytecode: options.bytecode,
+    });
+
+    try {
+        const result = await runBunBuildOrThrow(buildOptions);
+        const outputs = await finalizeBuildOutputs({
+            result,
+            cwd: options.cwd,
+            outfile: options.outfile,
+            outDir,
+            compile: options.compile,
+        });
+        return { success: result.success ?? false, hasPages, outputs };
+    } finally {
+        cleanupVirtualEntry(virtualSourcePath);
+        cleanupEntryOptionsModule(entryOptions.tempFilePath);
+    }
+}

package/src/utils/build/project.ts

@@ -0,0 +1,21 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Read the project name from package.json.
+ * Falls back to 'app' if not found or on any error.
+ */
+export function getProjectName(cwd: string = process.cwd()): string {
+    try {
+        const packageJsonPath = join(cwd, 'package.json');
+        if (existsSync(packageJsonPath)) {
+            const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8')) as {
+                name?: string;
+            };
+            return pkg?.name || 'app';
+        }
+    } catch {
+        // Ignore — use fallback
+    }
+    return 'app';
+}

package/src/utils/config.ts

@@ -7,7 +7,9 @@
 
 import { existsSync } from 'fs';
 import { join } from 'path';
+import { pathToFileURL } from 'url';
 import type { BuildConfig } from '../types/index';
+import { warning } from './logger';
 
 const CONVENTION_DEFAULTS: BuildConfig = {
     apiDir: './src/api',
@@ -41,15 +43,16 @@ export async function resolveBuildConfig(cwd: string): Promise<BuildConfig> {
     }
 
     try {
-        const mod = await import(configPath);
+        const configUrl = pathToFileURL(configPath).href;
+        const mod = await import(configUrl);
         const user = mod.default ?? mod;
         if (!user || typeof user !== 'object') {
             return { ...CONVENTION_DEFAULTS };
         }
         return mergeBuildConfig(CONVENTION_DEFAULTS, user);
     } catch (err) {
-        console.warn(
-            `[burger-api] Could not load ${configPath}: ${err instanceof Error ? err.message : String(err)}. Using convention defaults.`
+        warning(
+            `Could not load ${configPath}: ${err instanceof Error ? err.message : String(err)}. Using convention defaults.`
         );
         return { ...CONVENTION_DEFAULTS };
     }
@@ -60,8 +63,7 @@ function mergeBuildConfig(
     user: Record<string, unknown>
 ): BuildConfig {
     return {
-        apiDir:
-            typeof user.apiDir === 'string' ? user.apiDir : defaults.apiDir,
+        apiDir: typeof user.apiDir === 'string' ? user.apiDir : defaults.apiDir,
         pageDir:
             typeof user.pageDir === 'string' ? user.pageDir : defaults.pageDir,
         apiPrefix:
@@ -72,7 +74,6 @@ function mergeBuildConfig(
             typeof user.pagePrefix === 'string'
                 ? user.pagePrefix
                 : defaults.pagePrefix,
-        debug:
-            typeof user.debug === 'boolean' ? user.debug : defaults.debug,
+        debug: typeof user.debug === 'boolean' ? user.debug : defaults.debug,
     };
 }

package/src/utils/github.ts

@@ -14,17 +14,37 @@ import type { GitHubFile, MiddlewareInfo } from '../types/index';
 import { unlinkSync } from 'fs';
 
 /**
- * Configuration for GitHub repository
- * Change these if you fork the project or want to test with a different repo
+ * Configuration for GitHub repository.
+ * Override via env: BURGER_API_REPO_OWNER, BURGER_API_REPO_NAME, BURGER_API_BRANCH.
  */
-const REPO_OWNER = 'isfhan';
-const REPO_NAME = 'burger-api';
-const BRANCH = 'main';
+const REPO_OWNER = process.env.BURGER_API_REPO_OWNER ?? 'isfhan';
+const REPO_NAME = process.env.BURGER_API_REPO_NAME ?? 'burger-api';
+const BRANCH = process.env.BURGER_API_BRANCH ?? 'main';
 
 // Build the URLs we'll use to access GitHub
 const RAW_URL = `https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/${BRANCH}`;
 const API_URL = `https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}`;
 
+const FETCH_TIMEOUT_MS = 20_000;
+
+function createFetchSignal(): AbortSignal {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    controller.signal.addEventListener('abort', () => clearTimeout(timer), {
+        once: true,
+    });
+    return controller.signal;
+}
+
+function wrapFetchError(err: unknown, fallbackMessage: string): Error {
+    if (err instanceof Error && err.name === 'AbortError') {
+        return new Error(
+            'Request timed out. Please check your internet connection.'
+        );
+    }
+    return new Error(err instanceof Error ? err.message : fallbackMessage);
+}
+
 /**
  * Get list of available middleware from GitHub
  * This scans the ecosystem/middlewares folder and returns what's available
@@ -41,9 +61,9 @@ export async function getMiddlewareList(): Promise<string[]> {
         const response = await fetch(
             `${API_URL}/contents/ecosystem/middlewares`,
             {
+                signal: createFetchSignal(),
                 headers: {
                     Accept: 'application/vnd.github.v3+json',
-                    // Add User-Agent to be nice to GitHub
                     'User-Agent': 'burger-api-cli',
                 },
             }
@@ -64,8 +84,8 @@ export async function getMiddlewareList(): Promise<string[]> {
             .map((f) => f.name)
             .sort();
     } catch (err) {
-        // Provide helpful error message
-        throw new Error(
+        throw wrapFetchError(
+            err,
             'Could not get middleware list from GitHub. Please check your internet connection.'
         );
     }
@@ -87,6 +107,7 @@ export async function getMiddlewareInfo(name: string): Promise<MiddlewareInfo> {
         const response = await fetch(
             `${API_URL}/contents/ecosystem/middlewares/${name}`,
             {
+                signal: createFetchSignal(),
                 headers: {
                     Accept: 'application/vnd.github.v3+json',
                     'User-Agent': 'burger-api-cli',
@@ -108,7 +129,9 @@ export async function getMiddlewareInfo(name: string): Promise<MiddlewareInfo> {
 
         if (readmeFile && readmeFile.download_url) {
             try {
-                const readmeResponse = await fetch(readmeFile.download_url);
+                const readmeResponse = await fetch(readmeFile.download_url, {
+                    signal: createFetchSignal(),
+                });
                 const readmeContent = await readmeResponse.text();
 
                 // Extract first non-empty line after the title as description
@@ -132,7 +155,10 @@ export async function getMiddlewareInfo(name: string): Promise<MiddlewareInfo> {
             files: files.map((f) => f.name),
         };
     } catch (err) {
-        throw new Error(`Could not get info for middleware "${name}"`);
+        throw wrapFetchError(
+            err,
+            `Could not get info for middleware "${name}"`
+        );
     }
 }
 
@@ -154,8 +180,9 @@ export async function downloadFile(
         // Build the URL to the raw file content
         const url = `${RAW_URL}/${path}`;
 
-        // Download using Bun's native fetch
-        const response = await fetch(url);
+        const response = await fetch(url, {
+            signal: createFetchSignal(),
+        });
 
         if (!response.ok) {
             throw new Error(`Could not download ${path}`);
@@ -168,7 +195,8 @@ export async function downloadFile(
         // Bun.write is much faster than Node's fs.writeFile!
         await Bun.write(destination, content);
     } catch (err) {
-        throw new Error(
+        throw wrapFetchError(
+            err,
             `Failed to download ${path}: ${
                 err instanceof Error ? err.message : 'Unknown error'
             }`
@@ -246,6 +274,7 @@ export async function middlewareExists(name: string): Promise<boolean> {
         const response = await fetch(
             `${API_URL}/contents/ecosystem/middlewares/${name}`,
             {
+                signal: createFetchSignal(),
                 headers: {
                     Accept: 'application/vnd.github.v3+json',
                     'User-Agent': 'burger-api-cli',

package/src/utils/logger.ts

@@ -379,6 +379,27 @@ export function spinner(message: string): Spinner {
     return new Spinner(message);
 }
 
+/**
+ * Run an async command with a spinner. On throw, stops the spinner with error state and rethrows.
+ * Use so catch blocks do not need to remember to stop the spinner.
+ *
+ * @param message - Spinner message
+ * @param fn - Async callback receiving the spinner
+ * @returns Result of fn
+ */
+export async function withSpinner<T>(
+    message: string,
+    fn: (spin: Spinner) => Promise<T>
+): Promise<T> {
+    const spin = new Spinner(message);
+    try {
+        return await fn(spin);
+    } catch (err) {
+        spin.stop(message.replace(/\s*\.\.\.\s*$/, '') + ' failed', true);
+        throw err;
+    }
+}
+
 /**
  * Format a file size in a human-readable way
  * Converts bytes to KB, MB, etc.

package/src/utils/templates.ts

@@ -30,7 +30,7 @@ export function generatePackageJson(projectName: string): string {
             build: 'bun build src/index.ts --outdir ./dist',
         },
         dependencies: {
-            'burger-api': '^0.9.0',
+            'burger-api': '^0.9.3',
         },
         devDependencies: {
             '@types/bun': 'latest',
@@ -962,7 +962,7 @@ export function generateIndexPage(projectName: string): string {
 
     <!-- Footer -->
     <footer class="footer">
-        <div class="version">BurgerAPI v0.9.0 • Bun v1.3+</div>
+        <div class="version">BurgerAPI v0.9.3 • Bun v1.3+</div>
         <div class="social-links">
             <a href="https://github.com/isfhan/burger-api" target="_blank">GitHub</a>
             <a href="https://www.npmjs.com/package/burger-api" target="_blank">NPM</a>
@@ -1142,7 +1142,12 @@ export async function installDependencies(projectDir: string): Promise<void> {
         const exitCode = await proc.exited;
 
         if (exitCode !== 0) {
-            throw new Error('bun install failed');
+            const stderrText = await new Response(proc.stderr).text();
+            const message =
+                stderrText.trim().length > 0
+                    ? `bun install failed:\n${stderrText.trim()}`
+                    : 'bun install failed';
+            throw new Error(message);
         }
 
         spin.stop('Dependencies installed!');