ecopages 0.2.0-beta.31 → 0.2.0-beta.33

package/README.md

@@ -79,11 +79,12 @@ Trace lines are prefixed with `[ecopages:startup-trace]` and look like:
 [ecopages:startup-trace] phase=setupAppRuntimePlugins durationMs=714 wallMs=1999
 [ecopages:startup-trace] phase=route-registry durationMs=1 wallMs=2000
 [ecopages:startup-trace] phase=server-listen durationMs=45 wallMs=2046
+[ecopages:startup-trace] phase=dev-client-transform durationMs=42 wallMs=2100
 [ecopages:startup-trace] phase=first-request-ssr durationMs=5296 wallMs=12495
 [ecopages:startup-trace] summary path=/docs/getting-started/introduction bundleCount=13 clientBundleBytes=858396 wallMs=12496
 ```
 
-Phases: config ready → runtime plugins → route registry → server listening → first request SSR. The summary includes bundle count and total client JS bytes for that first request.
+Phases: config ready → runtime plugins → route registry → server listening → first request SSR (with per-module `dev-client-transform` on demand for `/assets/__eco_dev__/` modules). The summary includes bundle count and total client JS bytes for that first request.
 
 ```bash
 # Focused perf trace only

package/bin/cli.js

@@ -1,335 +1,387 @@
 #!/usr/bin/env node
-import { downloadTemplate } from "giget";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { spawn } from "node:child_process";
-import { join } from "node:path";
-import { parseArgs } from "node:util";
-import { Logger } from "@ecopages/logger";
-import { createLaunchPlan } from "./launch-plan.js";
-const logger = new Logger("[ecopages:cli]", { debug: process.env.ECOPAGES_LOGGER_DEBUG === "true" });
-const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
+
+import { downloadTemplate } from 'giget';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { Logger } from '@ecopages/logger';
+import { createLaunchPlan } from './launch-plan.js';
+
+const logger = new Logger('[ecopages:cli]', { debug: process.env.ECOPAGES_LOGGER_DEBUG === 'true' });
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
+
 const sharedServerOptionDefinitions = {
-  port: {
-    type: "string",
-    short: "p"
-  },
-  hostname: {
-    type: "string",
-    short: "n"
-  },
-  "base-url": {
-    type: "string",
-    short: "b"
-  },
-  debug: {
-    type: "boolean",
-    short: "d"
-  },
-  "react-fast-refresh": {
-    type: "boolean",
-    short: "r"
-  },
-  runtime: {
-    type: "string"
-  },
-  "entry-file": {
-    type: "string",
-    short: "e"
-  },
-  help: {
-    type: "boolean",
-    short: "h"
-  }
+	port: {
+		type: 'string',
+		short: 'p',
+	},
+	hostname: {
+		type: 'string',
+		short: 'n',
+	},
+	'base-url': {
+		type: 'string',
+		short: 'b',
+	},
+	debug: {
+		type: 'boolean',
+		short: 'd',
+	},
+	'react-fast-refresh': {
+		type: 'boolean',
+		short: 'r',
+	},
+	runtime: {
+		type: 'string',
+	},
+	'entry-file': {
+		type: 'string',
+		short: 'e',
+	},
+	help: {
+		type: 'boolean',
+		short: 'h',
+	},
 };
+
 const initOptionDefinitions = {
-  template: {
-    type: "string"
-  },
-  repo: {
-    type: "string"
-  },
-  help: {
-    type: "boolean",
-    short: "h"
-  }
+	template: {
+		type: 'string',
+	},
+	repo: {
+		type: 'string',
+	},
+	help: {
+		type: 'boolean',
+		short: 'h',
+	},
 };
+
 function getMainHelpText() {
-  return [
-    `ecopages ${pkg.version}`,
-    "",
-    "Usage: ecopages <command> [options]",
-    "",
-    "Commands:",
-    "  init <dir>              Initialize a new project from a template",
-    "  dev                     Start the development server",
-    "  dev:watch               Start the development server with watch mode",
-    "  dev:hot                 Start the development server with hot reload",
-    "  build                   Build the project for production",
-    "  start                   Start the production server",
-    "  preview                 Preview the production build",
-    "",
-    "Global options:",
-    "  -e, --entry-file <file> Entry file (default: app.ts)",
-    "  -h, --help              Show help",
-    "  --version               Show version"
-  ].join("\n");
+	return [
+		`ecopages ${pkg.version}`,
+		'',
+		'Usage: ecopages <command> [options]',
+		'',
+		'Commands:',
+		'  init <dir>              Initialize a new project from a template',
+		'  dev                     Start the development server',
+		'  dev:watch               Start the development server with watch mode',
+		'  dev:hot                 Start the development server with hot reload',
+		'  build                   Build the project for production',
+		'  start                   Start the production server',
+		'  preview                 Preview the production build',
+		'',
+		'Global options:',
+		'  -e, --entry-file <file> Entry file (default: app.ts)',
+		'  -h, --help              Show help',
+		'  --version               Show version',
+	].join('\n');
 }
+
 function getServerCommandHelpText(commandName, description) {
-  return [
-    `Usage: ecopages ${commandName} [options]`,
-    "",
-    description,
-    "",
-    "Options:",
-    "  -p, --port <port>                       Override ECOPAGES_PORT",
-    "  -n, --hostname <hostname>               Override ECOPAGES_HOSTNAME",
-    "  -b, --base-url <baseUrl>                Override ECOPAGES_BASE_URL",
-    "  -d, --debug                             Enable debug logging",
-    "  -r, --react-fast-refresh                Enable React Fast Refresh for Bun HMR",
-    "      --runtime <runtime>                 Force bun or node",
-    "  -e, --entry-file <file>                 Entry file (default: app.ts)",
-    "  -h, --help                              Show help"
-  ].join("\n");
+	return [
+		`Usage: ecopages ${commandName} [options]`,
+		'',
+		description,
+		'',
+		'Options:',
+		'  -p, --port <port>                       Override ECOPAGES_PORT',
+		'  -n, --hostname <hostname>               Override ECOPAGES_HOSTNAME',
+		'  -b, --base-url <baseUrl>                Override ECOPAGES_BASE_URL',
+		'  -d, --debug                             Enable debug logging',
+		'  -r, --react-fast-refresh                Enable React Fast Refresh for Bun HMR',
+		'      --runtime <runtime>                 Force bun or node',
+		'  -e, --entry-file <file>                 Entry file (default: app.ts)',
+		'  -h, --help                              Show help',
+	].join('\n');
 }
+
 function getBuildCommandHelpText() {
-  return [
-    "Usage: ecopages build [options]",
-    "",
-    "Build the project for production.",
-    "",
-    "Options:",
-    "  -p, --port <port>                       Override ECOPAGES_PORT",
-    "  -n, --hostname <hostname>               Override ECOPAGES_HOSTNAME",
-    "  -b, --base-url <baseUrl>                Override ECOPAGES_BASE_URL",
-    "  -d, --debug                             Enable debug logging",
-    "  -r, --react-fast-refresh                Enable React Fast Refresh for Bun HMR",
-    "      --runtime <runtime>                 Force bun or node",
-    "  -e, --entry-file <file>                 Entry file (default: app.ts)",
-    "  -h, --help                              Show help"
-  ].join("\n");
+	return [
+		'Usage: ecopages build [options]',
+		'',
+		'Build the project for production.',
+		'',
+		'Options:',
+		'  -p, --port <port>                       Override ECOPAGES_PORT',
+		'  -n, --hostname <hostname>               Override ECOPAGES_HOSTNAME',
+		'  -b, --base-url <baseUrl>                Override ECOPAGES_BASE_URL',
+		'  -d, --debug                             Enable debug logging',
+		'  -r, --react-fast-refresh                Enable React Fast Refresh for Bun HMR',
+		'      --runtime <runtime>                 Force bun or node',
+		'  -e, --entry-file <file>                 Entry file (default: app.ts)',
+		'  -h, --help                              Show help',
+	].join('\n');
 }
+
 function getInitCommandHelpText() {
-  return [
-    "Usage: ecopages init <dir> [options]",
-    "",
-    "Initialize a new project from a template.",
-    "",
-    "Options:",
-    "      --template <template>               Template name from ecopages/examples/",
-    "      --repo <repo>                       GitHub repo in user/repo form",
-    "  -h, --help                              Show help"
-  ].join("\n");
+	return [
+		'Usage: ecopages init <dir> [options]',
+		'',
+		'Initialize a new project from a template.',
+		'',
+		'Options:',
+		'      --template <template>               Template name from ecopages/examples/',
+		'      --repo <repo>                       GitHub repo in user/repo form',
+		'  -h, --help                              Show help',
+	].join('\n');
 }
+
 function parseCommandArguments(rawArgs, options) {
-  return parseArgs({
-    args: rawArgs,
-    options,
-    allowPositionals: true,
-    strict: true
-  });
+	return parseArgs({
+		args: rawArgs,
+		options,
+		allowPositionals: true,
+		strict: true,
+	});
 }
-function parseServerCommandArgs(rawArgs, commandName, description, mode = "server") {
-  const { values, positionals } = parseCommandArguments(rawArgs, sharedServerOptionDefinitions);
-  if (values.help) {
-    console.log(mode === "build" ? getBuildCommandHelpText() : getServerCommandHelpText(commandName, description));
-    return { help: true };
-  }
-  if (positionals.length > 0) {
-    throw new Error(
-      `Positional entry file arguments are not supported for \`${commandName}\`. Use --entry-file <file> instead.`
-    );
-  }
-  const entry = values["entry-file"] ?? "app.ts";
-  return {
-    entry,
-    options: {
-      port: values.port,
-      hostname: values.hostname,
-      baseUrl: values["base-url"],
-      debug: values.debug,
-      reactFastRefresh: values["react-fast-refresh"],
-      runtime: values.runtime
-    }
-  };
+
+function parseServerCommandArgs(rawArgs, commandName, description, mode = 'server') {
+	const { values, positionals } = parseCommandArguments(rawArgs, sharedServerOptionDefinitions);
+
+	if (values.help) {
+		console.log(mode === 'build' ? getBuildCommandHelpText() : getServerCommandHelpText(commandName, description));
+		return { help: true };
+	}
+
+	if (positionals.length > 0) {
+		throw new Error(
+			`Positional entry file arguments are not supported for \`${commandName}\`. Use --entry-file <file> instead.`,
+		);
+	}
+
+	const entry = values['entry-file'] ?? 'app.ts';
+
+	return {
+		entry,
+		options: {
+			port: values.port,
+			hostname: values.hostname,
+			baseUrl: values['base-url'],
+			debug: values.debug,
+			reactFastRefresh: values['react-fast-refresh'],
+			runtime: values.runtime,
+		},
+	};
 }
+
 function parseInitCommandArgs(rawArgs) {
-  const { values, positionals } = parseCommandArguments(rawArgs, initOptionDefinitions);
-  if (values.help) {
-    console.log(getInitCommandHelpText());
-    return { help: true };
-  }
-  if (positionals.length !== 1) {
-    throw new Error("The `init` command requires exactly one target directory argument.");
-  }
-  return {
-    dir: positionals[0],
-    template: values.template ?? "starter-jsx",
-    repo: values.repo ?? "ecopages/ecopages"
-  };
+	const { values, positionals } = parseCommandArguments(rawArgs, initOptionDefinitions);
+
+	if (values.help) {
+		console.log(getInitCommandHelpText());
+		return { help: true };
+	}
+
+	if (positionals.length !== 1) {
+		throw new Error('The `init` command requires exactly one target directory argument.');
+	}
+
+	return {
+		dir: positionals[0],
+		template: values.template ?? 'starter-jsx',
+		repo: values.repo ?? 'ecopages/ecopages',
+	};
 }
+
 function runLaunchPlan(launchPlan) {
-  if (Object.keys(launchPlan.envOverrides).length > 0) {
-    logger.debug(`Environment overrides: ${JSON.stringify(launchPlan.envOverrides)}`);
-  }
-  logger.debug(`Runtime: ${launchPlan.runtime}`);
-  logger.debug(`Running: ${launchPlan.command} ${launchPlan.commandArgs.join(" ")}`);
-  const child = spawn(launchPlan.command, launchPlan.commandArgs, {
-    stdio: "inherit",
-    env: launchPlan.env
-  });
-  child.on("error", (error) => {
-    if (error && error.code === "ENOENT") {
-      const hint = launchPlan.runtime === "bun" ? "Install Bun from https://bun.sh to continue." : "Reinstall Node.js or run with --runtime bun if this app requires Bun.";
-      logger.error(`Command not found: ${launchPlan.command}. ${hint}`);
-      process.exit(1);
-    }
-    logger.error(`Failed to run command: ${error.message}`);
-    process.exit(1);
-  });
-  child.on("exit", (code) => {
-    process.exit(code || 0);
-  });
+	if (Object.keys(launchPlan.envOverrides).length > 0) {
+		logger.debug(`Environment overrides: ${JSON.stringify(launchPlan.envOverrides)}`);
+	}
+
+	logger.debug(`Runtime: ${launchPlan.runtime}`);
+	logger.debug(`Running: ${launchPlan.command} ${launchPlan.commandArgs.join(' ')}`);
+
+	const child = spawn(launchPlan.command, launchPlan.commandArgs, {
+		stdio: 'inherit',
+		env: launchPlan.env,
+	});
+
+	child.on('error', (error) => {
+		if (error && error.code === 'ENOENT') {
+			const hint =
+				launchPlan.runtime === 'bun'
+					? 'Install Bun from https://bun.sh to continue.'
+					: 'Reinstall Node.js or run with --runtime bun if this app requires Bun.';
+			logger.error(`Command not found: ${launchPlan.command}. ${hint}`);
+			process.exit(1);
+		}
+
+		logger.error(`Failed to run command: ${error.message}`);
+		process.exit(1);
+	});
+
+	child.on('exit', (code) => {
+		process.exit(code || 0);
+	});
 }
-async function runEntryCommand(args, options = {}, entryFile = "app.ts", launchMode = "start") {
-  let launchPlan;
-  const requiresBuiltBundle = launchMode === "start";
-  if (!requiresBuiltBundle && !existsSync(entryFile)) {
-    logger.error(`Error: Entry file "${entryFile}" not found in the current directory.`);
-    process.exit(1);
-  }
-  try {
-    launchPlan = await createLaunchPlan(args, options, entryFile, launchMode);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    logger.error(message);
-    process.exit(1);
-  }
-  runLaunchPlan(launchPlan);
+
+/**
+ * Launch the entry file via the detected or forced runtime.
+ * Node uses native Node semantics; Bun uses Bun runtime flags.
+ * @param {string[]} args - Arguments to pass to the entry file
+ * @param {object} options - CLI options (watch, hot, port, hostname, etc.)
+ * @param {string} entryFile - Entry file to run
+ */
+async function runEntryCommand(args, options = {}, entryFile = 'app.ts', launchMode = 'start') {
+	let launchPlan;
+	const requiresBuiltBundle = launchMode === 'start';
+
+	if (!requiresBuiltBundle && !existsSync(entryFile)) {
+		logger.error(`Error: Entry file "${entryFile}" not found in the current directory.`);
+		process.exit(1);
+	}
+
+	try {
+		launchPlan = await createLaunchPlan(args, options, entryFile, launchMode);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		logger.error(message);
+		process.exit(1);
+	}
+
+	runLaunchPlan(launchPlan);
 }
+
 async function runInitCommand(rawArgs) {
-  const parsed = parseInitCommandArgs(rawArgs);
-  if (parsed.help) {
-    return;
-  }
-  const { dir, template, repo } = parsed;
-  if (existsSync(dir)) {
-    logger.error(`Target directory already exists: ${dir}`);
-    process.exit(1);
-  }
-  logger.info(`Creating target directory '${dir}'...`);
-  try {
-    await downloadTemplate(`github:${repo}/examples/${template}`, {
-      dir,
-      force: true
-    });
-    const pkgPath = join(dir, "package.json");
-    if (existsSync(pkgPath)) {
-      const projectPkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-      projectPkg.name = dir;
-      writeFileSync(pkgPath, JSON.stringify(projectPkg, null, 2) + "\n");
-      logger.info(`Renamed project to '${dir}'`);
-    }
-    logger.info("Project initialized! Run `bun install && bun dev` to start.");
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    logger.error(`Failed to fetch template: ${message}`);
-    process.exit(1);
-  }
+	const parsed = parseInitCommandArgs(rawArgs);
+
+	if (parsed.help) {
+		return;
+	}
+
+	const { dir, template, repo } = parsed;
+
+	if (existsSync(dir)) {
+		logger.error(`Target directory already exists: ${dir}`);
+		process.exit(1);
+	}
+
+	logger.info(`Creating target directory '${dir}'...`);
+
+	try {
+		await downloadTemplate(`github:${repo}/examples/${template}`, {
+			dir,
+			force: true,
+		});
+
+		const pkgPath = join(dir, 'package.json');
+		if (existsSync(pkgPath)) {
+			const projectPkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+			projectPkg.name = dir;
+			writeFileSync(pkgPath, JSON.stringify(projectPkg, null, 2) + '\n');
+			logger.info(`Renamed project to '${dir}'`);
+		}
+
+		logger.info('Project initialized! Run `bun install && bun dev` to start.');
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		logger.error(`Failed to fetch template: ${message}`);
+		process.exit(1);
+	}
 }
+
 async function runServerCommand(rawArgs, definition) {
-  const parsed = parseServerCommandArgs(rawArgs, definition.name, definition.description, definition.mode);
-  if (parsed.help) {
-    return;
-  }
-  await runEntryCommand(
-    definition.entryArgs,
-    { ...parsed.options, ...definition.optionOverrides, entryFile: parsed.entry },
-    parsed.entry,
-    definition.launchMode ?? definition.name
-  );
+	const parsed = parseServerCommandArgs(rawArgs, definition.name, definition.description, definition.mode);
+
+	if (parsed.help) {
+		return;
+	}
+
+	await runEntryCommand(
+		definition.entryArgs,
+		{ ...parsed.options, ...definition.optionOverrides, entryFile: parsed.entry },
+		parsed.entry,
+		definition.launchMode ?? definition.name,
+	);
 }
-async function runCli(rawArgs = process.argv.slice(2)) {
-  const [commandName, ...commandArgs] = rawArgs;
-  if (!commandName || commandName === "--help" || commandName === "-h") {
-    console.log(getMainHelpText());
-    return;
-  }
-  if (commandName === "--version") {
-    console.log(pkg.version);
-    return;
-  }
-  try {
-    switch (commandName) {
-      case "init":
-        await runInitCommand(commandArgs);
-        return;
-      case "dev":
-        await runServerCommand(commandArgs, {
-          name: "dev",
-          description: "Start the development server.",
-          entryArgs: ["--dev"],
-          launchMode: "dev",
-          optionOverrides: { nodeEnv: "development" }
-        });
-        return;
-      case "dev:watch":
-        await runServerCommand(commandArgs, {
-          name: "dev:watch",
-          description: "Start the development server with watch mode.",
-          entryArgs: ["--dev"],
-          launchMode: "dev",
-          optionOverrides: { watch: true, nodeEnv: "development" }
-        });
-        return;
-      case "dev:hot":
-        await runServerCommand(commandArgs, {
-          name: "dev:hot",
-          description: "Start the development server with hot reload.",
-          entryArgs: ["--dev"],
-          launchMode: "dev",
-          optionOverrides: { hot: true, nodeEnv: "development" }
-        });
-        return;
-      case "build":
-        await runServerCommand(commandArgs, {
-          name: "build",
-          description: "Build the project for production.",
-          entryArgs: ["--build"],
-          launchMode: "build",
-          optionOverrides: { nodeEnv: "production" },
-          mode: "build"
-        });
-        return;
-      case "start":
-        await runServerCommand(commandArgs, {
-          name: "start",
-          description: "Start the production server.",
-          entryArgs: [],
-          launchMode: "start",
-          optionOverrides: { nodeEnv: "production" }
-        });
-        return;
-      case "preview":
-        await runServerCommand(commandArgs, {
-          name: "preview",
-          description: "Preview the production build.",
-          entryArgs: ["--preview"],
-          launchMode: "preview",
-          optionOverrides: { nodeEnv: "production" }
-        });
-        return;
-      default:
-        throw new Error(`Unknown command \`${commandName}\`.`);
-    }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    logger.error(message);
-    process.exit(1);
-  }
+
+export async function runCli(rawArgs = process.argv.slice(2)) {
+	const [commandName, ...commandArgs] = rawArgs;
+
+	if (!commandName || commandName === '--help' || commandName === '-h') {
+		console.log(getMainHelpText());
+		return;
+	}
+
+	if (commandName === '--version') {
+		console.log(pkg.version);
+		return;
+	}
+
+	try {
+		switch (commandName) {
+			case 'init':
+				await runInitCommand(commandArgs);
+				return;
+			case 'dev':
+				await runServerCommand(commandArgs, {
+					name: 'dev',
+					description: 'Start the development server.',
+					entryArgs: ['--dev'],
+					launchMode: 'dev',
+					optionOverrides: { nodeEnv: 'development' },
+				});
+				return;
+			case 'dev:watch':
+				await runServerCommand(commandArgs, {
+					name: 'dev:watch',
+					description: 'Start the development server with watch mode.',
+					entryArgs: ['--dev'],
+					launchMode: 'dev',
+					optionOverrides: { watch: true, nodeEnv: 'development' },
+				});
+				return;
+			case 'dev:hot':
+				await runServerCommand(commandArgs, {
+					name: 'dev:hot',
+					description: 'Start the development server with hot reload.',
+					entryArgs: ['--dev'],
+					launchMode: 'dev',
+					optionOverrides: { hot: true, nodeEnv: 'development' },
+				});
+				return;
+			case 'build':
+				await runServerCommand(commandArgs, {
+					name: 'build',
+					description: 'Build the project for production.',
+					entryArgs: ['--build'],
+					launchMode: 'build',
+					optionOverrides: { nodeEnv: 'production' },
+					mode: 'build',
+				});
+				return;
+			case 'start':
+				await runServerCommand(commandArgs, {
+					name: 'start',
+					description: 'Start the production server.',
+					entryArgs: [],
+					launchMode: 'start',
+					optionOverrides: { nodeEnv: 'production' },
+				});
+				return;
+			case 'preview':
+				await runServerCommand(commandArgs, {
+					name: 'preview',
+					description: 'Preview the production build.',
+					entryArgs: ['--preview'],
+					launchMode: 'preview',
+					optionOverrides: { nodeEnv: 'production' },
+				});
+				return;
+			default:
+				throw new Error(`Unknown command \`${commandName}\`.`);
+		}
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		logger.error(message);
+		process.exit(1);
+	}
 }
+
 if (!process.env.VITEST) {
-  runCli();
+	runCli();
 }
-export {
-  runCli
-};

package/bin/launch-plan.js

@@ -1,156 +1,206 @@
-import { existsSync, readFileSync } from "node:fs";
-import path from "node:path";
-import { parseEnv } from "node:util";
-import { SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME } from "@ecopages/core/utils/resolve-entry-file";
-const SERVER_BUNDLE_MANIFEST_FILENAME = "manifest.json";
-const nodeRequirePreload = import.meta.resolve("./node-require-preload.js");
-const tsxLoader = import.meta.resolve("tsx/esm");
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseEnv } from 'node:util';
+import { SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME } from '@ecopages/core/utils/resolve-entry-file';
+
+const SERVER_BUNDLE_MANIFEST_FILENAME = 'manifest.json';
+
+const nodeRequirePreload = import.meta.resolve('./node-require-preload.js');
+const tsxLoader = import.meta.resolve('tsx/esm');
+
 function getEnvFilePaths(nodeEnv) {
-  const envFiles = [".env", ".env.local"];
-  if (nodeEnv) {
-    envFiles.push(`.env.${nodeEnv}`, `.env.${nodeEnv}.local`);
-  }
-  return envFiles.filter((envFile) => existsSync(envFile));
+	const envFiles = ['.env', '.env.local'];
+
+	if (nodeEnv) {
+		envFiles.push(`.env.${nodeEnv}`, `.env.${nodeEnv}.local`);
+	}
+
+	return envFiles.filter((envFile) => existsSync(envFile));
 }
-function buildEnvOverrides(options) {
-  const env = {};
-  if (options.port) env.ECOPAGES_PORT = String(options.port);
-  if (options.hostname) env.ECOPAGES_HOSTNAME = options.hostname;
-  if (options.baseUrl) env.ECOPAGES_BASE_URL = options.baseUrl;
-  if (options.debug) env.ECOPAGES_LOGGER_DEBUG = "true";
-  if (options.nodeEnv) env.NODE_ENV = options.nodeEnv;
-  if (options.entryFile) env.ECOPAGES_ENTRY_FILE = options.entryFile;
-  return env;
+
+export function buildEnvOverrides(options) {
+	const env = {};
+	if (options.port) env.ECOPAGES_PORT = String(options.port);
+	if (options.hostname) env.ECOPAGES_HOSTNAME = options.hostname;
+	if (options.baseUrl) env.ECOPAGES_BASE_URL = options.baseUrl;
+	if (options.debug) env.ECOPAGES_LOGGER_DEBUG = 'true';
+	if (options.nodeEnv) env.NODE_ENV = options.nodeEnv;
+	if (options.entryFile) env.ECOPAGES_ENTRY_FILE = options.entryFile;
+	return env;
 }
-function buildLaunchEnv(options) {
-  const envOverrides = buildEnvOverrides(options);
-  const envFileValues = getEnvFilePaths(options.nodeEnv).reduce((env, envFile) => {
-    return { ...env, ...parseEnv(readFileSync(envFile, "utf8")) };
-  }, {});
-  return {
-    envOverrides,
-    env: { ...envFileValues, ...process.env, ...envOverrides }
-  };
+
+export function buildLaunchEnv(options) {
+	const envOverrides = buildEnvOverrides(options);
+	const envFileValues = getEnvFilePaths(options.nodeEnv).reduce((env, envFile) => {
+		return { ...env, ...parseEnv(readFileSync(envFile, 'utf8')) };
+	}, {});
+
+	return {
+		envOverrides,
+		env: { ...envFileValues, ...process.env, ...envOverrides },
+	};
 }
-function detectRuntime(options = {}) {
-  if (options.runtime === "bun" || options.runtime === "node") {
-    return options.runtime;
-  }
-  const userAgent = process.env.npm_config_user_agent || "";
-  if (userAgent.startsWith("bun/")) {
-    return "bun";
-  }
-  if (typeof Bun !== "undefined") {
-    return "bun";
-  }
-  return "node";
+
+export function detectRuntime(options = {}) {
+	if (options.runtime === 'bun' || options.runtime === 'node') {
+		return options.runtime;
+	}
+
+	const userAgent = process.env.npm_config_user_agent || '';
+
+	if (userAgent.startsWith('bun/')) {
+		return 'bun';
+	}
+
+	if (typeof Bun !== 'undefined') {
+		return 'bun';
+	}
+
+	return 'node';
 }
-function buildBunArgs(args, options, entryFile, hasConfig) {
-  const bunArgs = [];
-  if (options.watch) bunArgs.push("--watch");
-  if (options.hot) bunArgs.push("--hot");
-  bunArgs.push("run");
-  if (hasConfig) {
-    bunArgs.push("--preload", `./eco.config.${"ts"}`);
-  }
-  bunArgs.push(entryFile, ...args);
-  if (options.reactFastRefresh) {
-    bunArgs.push("--react-fast-refresh");
-  }
-  return bunArgs;
+
+export function buildBunArgs(args, options, entryFile, hasConfig) {
+	const bunArgs = [];
+
+	if (options.watch) bunArgs.push('--watch');
+	if (options.hot) bunArgs.push('--hot');
+
+	bunArgs.push('run');
+
+	if (hasConfig) {
+		bunArgs.push('--preload', `./eco.config.${'ts'}`);
+	}
+
+	bunArgs.push(entryFile, ...args);
+
+	if (options.reactFastRefresh) {
+		bunArgs.push('--react-fast-refresh');
+	}
+
+	return bunArgs;
 }
+
 function usesProductionBundle(launchMode) {
-  return launchMode === "start";
+	return launchMode === 'start';
 }
+
 function inferLaunchMode(args, launchMode) {
-  if (launchMode) {
-    return launchMode;
-  }
-  if (args.includes("--build")) {
-    return "build";
-  }
-  if (args.includes("--preview")) {
-    return "preview";
-  }
-  if (args.includes("--dev")) {
-    return "dev";
-  }
-  return "start";
+	if (launchMode) {
+		return launchMode;
+	}
+
+	if (args.includes('--build')) {
+		return 'build';
+	}
+
+	if (args.includes('--preview')) {
+		return 'preview';
+	}
+
+	if (args.includes('--dev')) {
+		return 'dev';
+	}
+
+	return 'start';
 }
+
+/**
+ * Builds the command and environment needed to launch the app.
+ *
+ * In `start` mode, the bundled server
+ * entry at `dist/{SERVER_BUNDLE_DIR}/{SERVER_BUNDLE_FILENAME}` is used
+ * directly. If the bundle is missing, an error is thrown directing the
+ * caller to run `ecopages build` first.
+ *
+ * In `build`, `dev`, and `preview` modes, the source entry file is executed via tsx
+ * (Node) or Bun's native runtime with the appropriate loader flags.
+ *
+ * @param {string[]} args - Arguments forwarded to the entry file.
+ * @param {object} options - CLI options (nodeEnv, runtime, port, etc.).
+ * @param {string} entryFile - Path to the entry file (default: `app.ts`).
+ * @param {'build' | 'dev' | 'preview' | 'start'} launchMode - The CLI command mode.
+ * @returns {{ runtime: string, command: string, commandArgs: string[], envOverrides: object, env: object }}
+ * @throws {Error} When `launchMode` is `start` and the bundle does not exist.
+ */
+
 function resolveProductionServerEntry(cwd = process.cwd()) {
-  const manifestPath = path.join(cwd, "dist", SERVER_BUNDLE_DIR, SERVER_BUNDLE_MANIFEST_FILENAME);
-  if (existsSync(manifestPath)) {
-    try {
-      const parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
-      if (parsed?.serverEntry) {
-        const fromManifest = path.isAbsolute(parsed.serverEntry) ? parsed.serverEntry : path.join(path.dirname(manifestPath), parsed.serverEntry);
-        if (existsSync(fromManifest)) {
-          return fromManifest;
-        }
-      }
-      if (parsed?.distDir) {
-        const fromDistDir = path.join(parsed.distDir, SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME);
-        if (existsSync(fromDistDir)) {
-          return fromDistDir;
-        }
-      }
-    } catch {
-    }
-  }
-  const legacyPath = path.join(cwd, "dist", SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME);
-  return existsSync(legacyPath) ? legacyPath : void 0;
+	const manifestPath = path.join(cwd, 'dist', SERVER_BUNDLE_DIR, SERVER_BUNDLE_MANIFEST_FILENAME);
+	if (existsSync(manifestPath)) {
+		try {
+			const parsed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+			if (parsed?.serverEntry) {
+				const fromManifest = path.isAbsolute(parsed.serverEntry)
+					? parsed.serverEntry
+					: path.join(path.dirname(manifestPath), parsed.serverEntry);
+				if (existsSync(fromManifest)) {
+					return fromManifest;
+				}
+			}
+			if (parsed?.distDir) {
+				const fromDistDir = path.join(parsed.distDir, SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME);
+				if (existsSync(fromDistDir)) {
+					return fromDistDir;
+				}
+			}
+		} catch {
+			// fall through to legacy path
+		}
+	}
+
+	const legacyPath = path.join(cwd, 'dist', SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME);
+	return existsSync(legacyPath) ? legacyPath : undefined;
 }
-function createLaunchPlan(args, options, entryFile, launchMode) {
-  const resolvedOptions = options ?? {};
-  const resolvedEntryFile = entryFile ?? "app.ts";
-  const { envOverrides, env } = buildLaunchEnv(resolvedOptions);
-  const runtime = detectRuntime(resolvedOptions);
-  const resolvedLaunchMode = inferLaunchMode(args, launchMode);
-  const distServerApp = resolveProductionServerEntry(process.cwd());
-  const shouldUseBundle = usesProductionBundle(resolvedLaunchMode);
-  const useBundle = shouldUseBundle && Boolean(distServerApp);
-  if (shouldUseBundle && !useBundle) {
-    throw new Error("No production bundle found. Run `ecopages build` before starting in production mode.");
-  }
-  if (useBundle) {
-    if (runtime === "node") {
-      return {
-        runtime,
-        command: process.execPath,
-        commandArgs: [distServerApp, ...args],
-        envOverrides,
-        env
-      };
-    }
-    return {
-      runtime,
-      command: "bun",
-      commandArgs: ["run", distServerApp, ...args],
-      envOverrides,
-      env
-    };
-  }
-  if (runtime === "node") {
-    return {
-      runtime,
-      command: process.execPath,
-      commandArgs: ["--import", nodeRequirePreload, "--import", tsxLoader, resolvedEntryFile, ...args],
-      envOverrides,
-      env
-    };
-  }
-  return {
-    runtime,
-    command: "bun",
-    commandArgs: buildBunArgs(args, resolvedOptions, resolvedEntryFile, existsSync("eco.config.ts")),
-    envOverrides,
-    env
-  };
+
+export function createLaunchPlan(args, options, entryFile, launchMode) {
+	const resolvedOptions = options ?? {};
+	const resolvedEntryFile = entryFile ?? 'app.ts';
+	const { envOverrides, env } = buildLaunchEnv(resolvedOptions);
+	const runtime = detectRuntime(resolvedOptions);
+	const resolvedLaunchMode = inferLaunchMode(args, launchMode);
+
+	const distServerApp = resolveProductionServerEntry(process.cwd());
+	const shouldUseBundle = usesProductionBundle(resolvedLaunchMode);
+	const useBundle = shouldUseBundle && Boolean(distServerApp);
+
+	if (shouldUseBundle && !useBundle) {
+		throw new Error('No production bundle found. Run `ecopages build` before starting in production mode.');
+	}
+
+	if (useBundle) {
+		if (runtime === 'node') {
+			return {
+				runtime,
+				command: process.execPath,
+				commandArgs: [distServerApp, ...args],
+				envOverrides,
+				env,
+			};
+		}
+
+		return {
+			runtime,
+			command: 'bun',
+			commandArgs: ['run', distServerApp, ...args],
+			envOverrides,
+			env,
+		};
+	}
+
+	if (runtime === 'node') {
+		return {
+			runtime,
+			command: process.execPath,
+			commandArgs: ['--import', nodeRequirePreload, '--import', tsxLoader, resolvedEntryFile, ...args],
+			envOverrides,
+			env,
+		};
+	}
+
+	return {
+		runtime,
+		command: 'bun',
+		commandArgs: buildBunArgs(args, resolvedOptions, resolvedEntryFile, existsSync('eco.config.ts')),
+		envOverrides,
+		env,
+	};
 }
-export {
-  buildBunArgs,
-  buildEnvOverrides,
-  buildLaunchEnv,
-  createLaunchPlan,
-  detectRuntime
-};

package/bin/node-require-preload.js

@@ -1,3 +1,4 @@
-import path from "node:path";
-import { createRequire } from "node:module";
-globalThis.require = createRequire(path.join(process.cwd(), "package.json"));
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+globalThis.require = createRequire(path.join(process.cwd(), 'package.json'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ecopages",
-  "version": "0.2.0-beta.31",
+  "version": "0.2.0-beta.33",
   "description": "CLI utilities for Ecopages",
   "type": "module",
   "engines": {
@@ -32,7 +32,7 @@
     "ecopages": "bin/cli.js"
   },
   "dependencies": {
-    "@ecopages/core": "0.2.0-beta.31",
+    "@ecopages/core": "0.2.0-beta.33",
     "@ecopages/logger": "^0.2.3",
     "giget": "^2.0.0",
     "tsx": "^4.22.3"