ecopages 0.2.0-alpha.5 → 0.2.0-alpha.6

package/README.md

@@ -1,16 +1,12 @@
 # ecopages
 
-> **DRAFT / EXPERIMENTAL**
-> This package is currently in a draft state and is subject to significant changes.
+The official CLI for the Ecopages framework.
 
-`ecopages` is a CLI tool for the Ecopages framework. It provides:
-
-- **Project scaffolding**: Quickly initialize new Ecopages projects from templates using `bunx ecopages init`
-- **Command utilities**: Namespaced commands that wrap common Bun operations, automatically detecting and applying your `eco.config.ts`
+It provides scaffolding and development commands to streamline your workflow. It natively wraps your execution environment (Bun or Node) and automatically detects your `eco.config.ts`.
 
 ## Quick Start
 
-Initialize a new project:
+Initialize a new project from the default template:
 
 ```bash
 bunx ecopages init my-app
@@ -19,91 +15,85 @@ bun install
 bun dev
 ```
 
-## CLI Utilities
+## Commands
 
-### Commands
+| Command                      | Description                                | Equivalent (Bun)                | Equivalent (Node)                             |
+| :--------------------------- | :----------------------------------------- | :------------------------------ | :-------------------------------------------- |
+| `ecopages init <dir>`        | Scaffolds a new project                    | N/A                             | N/A                                           |
+| `ecopages dev [entry]`       | Starts the dev server                      | `bun run [entry] --dev`         | `node [ecopages thin host] [entry] --dev`     |
+| `ecopages dev:watch [entry]` | Dev server + hard restarts on file changes | `bun --watch run [entry] --dev` | `node --watch [ecopages thin host] ...`       |
+| `ecopages dev:hot [entry]`   | Dev server + HMR (no hard restarts)        | `bun --hot run [entry] --dev`   | N/A                                           |
+| `ecopages build [entry]`     | Creates a production build                 | `bun run [entry] --build`       | `node [ecopages thin host] [entry] --build`   |
+| `ecopages start [entry]`     | Starts the production server               | `bun run [entry]`               | `node [ecopages thin host] [entry]`           |
+| `ecopages preview [entry]`   | Previews the production build locally      | `bun run [entry] --preview`     | `node [ecopages thin host] [entry] --preview` |
 
-| Command                      | Description                                      | Bun Equivalent                  |
-| :--------------------------- | :----------------------------------------------- | :------------------------------ |
-| `ecopages init <dir>`        | Initialize a new Ecopages project                | scaffolding tool                |
-| `ecopages dev [entry]`       | Start the development server                     | `bun run [entry] --dev`         |
-| `ecopages dev:watch [entry]` | Start with watch mode (restarts on file changes) | `bun --watch run [entry] --dev` |
-| `ecopages dev:hot [entry]`   | Start with hot reload (HMR without restart)      | `bun --hot run [entry] --dev`   |
-| `ecopages build [entry]`     | Build for production                             | `bun run [entry] --build`       |
-| `ecopages start [entry]`     | Start production server                          | `bun run [entry]`               |
-| `ecopages preview [entry]`   | Preview production build                         | `bun run [entry] --preview`     |
+> [!NOTE]
+> `[entry]` defaults to `app.ts` if not provided.
 
-> **Note:** `[entry]` defaults to `app.ts` if not provided.
+## Environment & Runtime Options
 
-### Environment Overrides
+Server and build commands accept the following options. They automatically map to the equivalent environment variables for the underlying process:
 
-All server commands (`dev`, `dev:watch`, `dev:hot`, `start`, `preview`) support the following options:
+| Option                     | Env Var                 | Description                                               |
+| :------------------------- | :---------------------- | :-------------------------------------------------------- |
+| `-p, --port <port>`        | `ECOPAGES_PORT`         | Server port (default 3000)                                |
+| `-n, --hostname <host>`    | `ECOPAGES_HOSTNAME`     | Server hostname                                           |
+| `-b, --base-url <url>`     | `ECOPAGES_BASE_URL`     | Base URL string                                           |
+| `-d, --debug`              | `ECOPAGES_LOGGER_DEBUG` | Enables debug-level logging                               |
+| `-r, --react-fast-refresh` |                         | Enables React Fast Refresh                                |
+| `--runtime <runtime>`      |                         | Force execution via `bun`, `node`, or `node-experimental` |
 
-| Option                     | Environment Variable    | Description                   |
-| :------------------------- | :---------------------- | :---------------------------- |
-| `-p, --port <port>`        | `ECOPAGES_PORT`         | Server port (default 3000)    |
-| `-n, --hostname <host>`    | `ECOPAGES_HOSTNAME`     | Server hostname               |
-| `-b, --base-url <url>`     | `ECOPAGES_BASE_URL`     | Base URL for the app          |
-| `-d, --debug`              | `ECOPAGES_LOGGER_DEBUG` | Enable debug logging          |
-| `-r, --react-fast-refresh` | -                       | Enable React Fast Refresh HMR |
+### Runtime Detection
 
-**Example:**
+The CLI automatically detects your runtime environments by inspecting the package manager (`npm_config_user_agent`) or whether the `Bun` global exists. If neither is forcing Bun, it executes your app through the Ecopages-owned Node thin host.
 
-```bash
-# Start dev server on port 8080 with debug logging
-ecopages dev --port 8080 --debug
+Both `node` and `node-experimental` now launch through the thin-host boundary and hand off the same serialized Node runtime manifest. `node-experimental` remains available as an explicit verification alias while the unified Node host path continues to settle.
 
-# Start dev server with React Fast Refresh
-ecopages dev -r
+You can explicitly force the engine using the `--runtime` flag:
 
-# Start production server with custom hostname
-ecopages start --hostname 0.0.0.0 --port 3001
+```bash
+ecopages dev --runtime node
+ecopages build --runtime bun
+ecopages dev --runtime node-experimental
 ```
 
-## Ecopages Packages
+### Example Usage
 
-The Ecopages ecosystem consists of individual framework packages published to [JSR](https://jsr.io/@ecopages). Import them directly in your project:
+```bash
+# Debug dev server on custom port
+ecopages dev --port 8080 --debug
 
-```typescript
-import { eco } from '@ecopages/core';
-import { kitajsPlugin } from '@ecopages/kitajs';
+# Dev server with React Fast Refresh enabled
+ecopages dev -r
 ```
 
-### Available Packages
-
-| Package                    | Description                                               | JSR Link                                       |
-| :------------------------- | :-------------------------------------------------------- | :--------------------------------------------- |
-| `@ecopages/browser-router` | Client-side navigation and view transitions for Ecopages. | [JSR](https://jsr.io/@ecopages/browser-router) |
+## Ecosystem & Plugins
 
-| `@ecopages/core` | Foundational layer of the Ecopages ecosystem. | [JSR](https://jsr.io/@ecopages/core) |
-| `@ecopages/file-system` | Runtime-agnostic file system utilities (Bun/Node.js). | [JSR](https://jsr.io/@ecopages/file-system) |
-| `@ecopages/image-processor` | Image processing library for optimized responsive images. | [JSR](https://jsr.io/@ecopages/image-processor) |
-| `@ecopages/kitajs` | KitaJS plugin for Ecopages integration. | [JSR](https://jsr.io/@ecopages/kitajs) |
-| `@ecopages/lit` | Lit plugin for Ecopages integration. | [JSR](https://jsr.io/@ecopages/lit) |
-| `@ecopages/mdx` | MDX plugin for Ecopages integration. | [JSR](https://jsr.io/@ecopages/mdx) |
-| `@ecopages/postcss-processor` | Utility functions for processing CSS with PostCSS. | [JSR](https://jsr.io/@ecopages/postcss-processor) |
-| `@ecopages/react` | React plugin for Ecopages integration. | [JSR](https://jsr.io/@ecopages/react) |
-| `@ecopages/react-router` | Client-side SPA router for Ecopages React apps. | [JSR](https://jsr.io/@ecopages/react-router) |
+Ecopages relies on a modular architecture. Core logic and framework integrations are published separately to [JSR](https://jsr.io/@ecopages).
 
-Explore all packages at [jsr.io/@ecopages](https://jsr.io/@ecopages).
-
-## Installation
-
-```bash
-bun add ecopages
-```
-
-To use Ecopages packages in your project, create a `.npmrc` file in the root of your project to configure JSR registry resolution:
+Configure your project to use JSR by adding a `.npmrc` file:
 
 ```ini
 @jsr:registry=https://npm.jsr.io
 ```
 
-Then add the packages you need:
+### Official Packages
+
+| Package                       | Description                                |
+| :---------------------------- | :----------------------------------------- |
+| `@ecopages/browser-router`    | Client-side navigation & view transitions. |
+| `@ecopages/codemod`           | AST migrations for codebase upgrades.      |
+| `@ecopages/core`              | The foundational SSG engine.               |
+| `@ecopages/file-system`       | Runtime-agnostic file system utilities.    |
+| `@ecopages/image-processor`   | Asset pipeline for responsive images.      |
+| `@ecopages/kitajs`            | Integration for KitaJS.                    |
+| `@ecopages/lit`               | Integration for Lit SSR/Islands.           |
+| `@ecopages/mdx`               | Integration for standalone MDX routes.     |
+| `@ecopages/postcss-processor` | CSS processing pipeline using PostCSS.     |
+| `@ecopages/react`             | Integration for React 19 SSR/Islands.      |
+| `@ecopages/react-router`      | SPA routing for React.                     |
 
-```bash
-bun jsr add @ecopages/core @ecopages/kitajs
-```
+Explore all packages at [jsr.io/@ecopages](https://jsr.io/@ecopages).
 
 ## License
 

package/bin/cli.js

@@ -6,6 +6,7 @@ import { spawn } from 'node:child_process';
 import { join } from 'node:path';
 import tiged from 'tiged';
 import { Logger } from '@ecopages/logger';
+import { createLaunchPlan, launchPlanRequiresExistingEntryFile } from './launch-plan.js';
 
 const logger = new Logger('[ecopages:cli]');
 
@@ -56,107 +57,6 @@ program
 	.option('--repo <repo>', 'GitHub repo (user/repo)', 'ecopages/ecopages')
 	.action(handleInit);
 
-/**
- * Build environment variables from CLI options
- */
-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;
-	return env;
-}
-
-function detectRuntime(options = {}) {
-	if (options.runtime === 'bun' || options.runtime === 'node') {
-		return options.runtime;
-	}
-
-	const userAgent = process.env.npm_config_user_agent || '';
-
-	/**
-	 * If explicitly launched via bun (e.g., `bun run ...`)
-	 */
-	if (userAgent.startsWith('bun/')) {
-		return 'bun';
-	}
-
-	/**
-	 * Catch when CLI is run directly by Bun without a package manager command
-	 */
-	if (typeof Bun !== 'undefined') {
-		return 'bun';
-	}
-
-	/**
-	 * Default to node for npm, pnpm, yarn, or direct execution
-	 */
-	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;
-}
-
-function buildNodeArgs(args, options, entryFile) {
-	const tsxArgs = [];
-
-	if (options.watch) tsxArgs.push('watch');
-
-	tsxArgs.push(entryFile, ...args);
-
-	if (options.reactFastRefresh) {
-		tsxArgs.push('--react-fast-refresh');
-	}
-
-	return tsxArgs;
-}
-
-function createLaunchPlan(args, options = {}, entryFile = 'app.ts') {
-	const hasConfig = existsSync('eco.config.ts');
-	const envOverrides = buildEnvOverrides(options);
-	const runtime = detectRuntime(options);
-
-	if (runtime === 'node') {
-		return {
-			runtime,
-			executionStrategy: 'tsx',
-			command: 'tsx',
-			commandArgs: buildNodeArgs(args, options, entryFile),
-			envOverrides,
-			env: { ...process.env, ...envOverrides },
-		};
-	}
-
-	return {
-		runtime,
-		executionStrategy: 'direct-runtime',
-		command: 'bun',
-		commandArgs: buildBunArgs(args, options, entryFile, hasConfig),
-		envOverrides,
-		env: { ...process.env, ...envOverrides },
-	};
-}
-
 function runLaunchPlan(launchPlan) {
 	if (Object.keys(launchPlan.envOverrides).length > 0) {
 		logger.info(`Environment overrides: ${JSON.stringify(launchPlan.envOverrides)}`);
@@ -175,7 +75,7 @@ function runLaunchPlan(launchPlan) {
 			const hint =
 				launchPlan.command === 'bun'
 					? 'Install Bun from https://bun.sh to continue.'
-					: 'Install tsx (`npm i -g tsx` or add it as a devDependency) to continue.';
+					: 'Install Node.js and ensure the `node` command is available to continue.';
 			logger.error(`Command not found: ${launchPlan.command}. ${hint}`);
 			process.exit(1);
 		}
@@ -196,13 +96,14 @@ function runLaunchPlan(launchPlan) {
  * @param {object} options - CLI options (watch, hot, port, hostname, etc.)
  * @param {string} entryFile - Entry file to run
  */
-function runBunCommand(args, options = {}, entryFile = 'app.ts') {
-	if (!existsSync(entryFile)) {
+async function runBunCommand(args, options = {}, entryFile = 'app.ts') {
+	const launchPlan = await createLaunchPlan(args, options, entryFile);
+
+	if (launchPlanRequiresExistingEntryFile(launchPlan) && !existsSync(entryFile)) {
 		logger.error(`Error: Entry file "${entryFile}" not found in the current directory.`);
 		process.exit(1);
 	}
 
-	const launchPlan = createLaunchPlan(args, options, entryFile);
 	runLaunchPlan(launchPlan);
 }
 
@@ -218,12 +119,12 @@ const serverOptions = (cmd) =>
 		.option('-b, --base-url <url>', 'Override ECOPAGES_BASE_URL')
 		.option('-d, --debug', 'Enable debug logging (ECOPAGES_LOGGER_DEBUG=true)')
 		.option('-r, --react-fast-refresh', 'Enable React Fast Refresh for HMR')
-		.option('--runtime <runtime>', 'Force a specific runtime (bun or node)');
+		.option('--runtime <runtime>', 'Force a specific runtime (bun, node, or node-experimental)');
 
 serverOptions(
 	program.command('dev').description('Start the development server').argument('[entry]', 'Entry file', 'app.ts'),
-).action((entry, opts) => {
-	runBunCommand(['--dev'], { ...opts, nodeEnv: 'development' }, entry);
+).action(async (entry, opts) => {
+	await runBunCommand(['--dev'], { ...opts, nodeEnv: 'development' }, entry);
 });
 
 serverOptions(
@@ -231,8 +132,8 @@ serverOptions(
 		.command('dev:watch')
 		.description('Start the development server with watch mode (restarts on file changes)')
 		.argument('[entry]', 'Entry file', 'app.ts'),
-).action((entry, opts) => {
-	runBunCommand(['--dev'], { ...opts, watch: true, nodeEnv: 'development' }, entry);
+).action(async (entry, opts) => {
+	await runBunCommand(['--dev'], { ...opts, watch: true, nodeEnv: 'development' }, entry);
 });
 
 serverOptions(
@@ -240,29 +141,29 @@ serverOptions(
 		.command('dev:hot')
 		.description('Start the development server with hot reload (HMR without restart)')
 		.argument('[entry]', 'Entry file', 'app.ts'),
-).action((entry, opts) => {
-	runBunCommand(['--dev'], { ...opts, hot: true, nodeEnv: 'development' }, entry);
+).action(async (entry, opts) => {
+	await runBunCommand(['--dev'], { ...opts, hot: true, nodeEnv: 'development' }, entry);
 });
 
 program
 	.command('build')
 	.description('Build the project for production')
 	.argument('[entry]', 'Entry file', 'app.ts')
-	.option('--runtime <runtime>', 'Force a specific runtime (bun or node)')
-	.action((entry, opts) => {
-		runBunCommand(['--build'], { nodeEnv: 'production', ...opts }, entry);
+	.option('--runtime <runtime>', 'Force a specific runtime (bun, node, or node-experimental)')
+	.action(async (entry, opts) => {
+		await runBunCommand(['--build'], { nodeEnv: 'production', ...opts }, entry);
 	});
 
 serverOptions(
 	program.command('start').description('Start the production server').argument('[entry]', 'Entry file', 'app.ts'),
-).action((entry, opts) => {
-	runBunCommand([], { ...opts, nodeEnv: 'production' }, entry);
+).action(async (entry, opts) => {
+	await runBunCommand([], { ...opts, nodeEnv: 'production' }, entry);
 });
 
 serverOptions(
 	program.command('preview').description('Preview the production build').argument('[entry]', 'Entry file', 'app.ts'),
-).action((entry, opts) => {
-	runBunCommand(['--preview'], { ...opts, nodeEnv: 'production' }, entry);
+).action(async (entry, opts) => {
+	await runBunCommand(['--preview'], { ...opts, nodeEnv: 'production' }, entry);
 });
 
 program.parse();

package/bin/launch-plan.js

@@ -0,0 +1,142 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const NODE_THIN_HOST_PATH = fileURLToPath(new URL('./node-thin-host.js', import.meta.url));
+const DEFAULT_INTERNAL_WORK_DIR = '.eco';
+
+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;
+	return env;
+}
+
+export function detectRuntime(options = {}) {
+	if (options.runtime === 'bun' || options.runtime === 'node' || options.runtime === 'node-experimental') {
+		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 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 buildNodeArgs(args, options, entryFile) {
+	const nodeArgs = [];
+
+	if (options.watch) nodeArgs.push('--watch');
+
+	nodeArgs.push(NODE_THIN_HOST_PATH, entryFile, ...args);
+
+	if (options.reactFastRefresh) {
+		nodeArgs.push('--react-fast-refresh');
+	}
+
+	return nodeArgs;
+}
+
+export function resolveNodeRuntimeManifestPath(projectDir = process.cwd()) {
+	return path.join(path.resolve(projectDir), DEFAULT_INTERNAL_WORK_DIR, 'runtime', 'node-runtime-manifest.json');
+}
+
+export async function createNodeRuntimeManifestFile(
+	entryFile,
+	options = {
+		cwd: process.cwd(),
+		env: process.env,
+	},
+) {
+	const projectDir = path.resolve(options.cwd ?? process.cwd());
+	const configPath = path.join(projectDir, 'eco.config.ts');
+	const manifestFilePath = options.manifestFilePath ?? resolveNodeRuntimeManifestPath(projectDir);
+
+	if (!existsSync(configPath)) {
+		throw new Error('The Node thin-host runtime requires eco.config.ts in the current project root.');
+	}
+
+	const manifest = {
+		runtime: 'node',
+		appRootDir: projectDir,
+		sourceRootDir: path.join(projectDir, 'src'),
+		distDir: path.join(projectDir, 'dist'),
+		workDir: path.join(projectDir, DEFAULT_INTERNAL_WORK_DIR),
+		modulePaths: {
+			config: configPath,
+			entry: path.resolve(projectDir, entryFile),
+		},
+	};
+
+	mkdirSync(path.dirname(manifestFilePath), { recursive: true });
+	writeFileSync(manifestFilePath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+
+	return manifestFilePath;
+}
+
+export async function createLaunchPlan(args, options = {}, entryFile = 'app.ts') {
+	const hasConfig = existsSync('eco.config.ts');
+	const envOverrides = buildEnvOverrides(options);
+	const runtime = detectRuntime(options);
+	const env = { ...process.env, ...envOverrides };
+
+	if (runtime === 'node' || runtime === 'node-experimental') {
+		const manifestFilePath = await createNodeRuntimeManifestFile(entryFile, { env });
+
+		return {
+			runtime,
+			executionStrategy: 'node-thin-host',
+			command: 'node',
+			commandArgs: buildNodeArgs(args, options, entryFile),
+			envOverrides,
+			env: {
+				...env,
+				ECOPAGES_NODE_RUNTIME_MANIFEST_PATH: manifestFilePath,
+			},
+		};
+	}
+
+	return {
+		runtime,
+		executionStrategy: 'direct-runtime',
+		command: 'bun',
+		commandArgs: buildBunArgs(args, options, entryFile, hasConfig),
+		envOverrides,
+		env,
+	};
+}
+
+export function launchPlanRequiresExistingEntryFile(launchPlan) {
+	return launchPlan.executionStrategy !== 'config-only-bootstrap';
+}

package/bin/launch-plan.test.ts

@@ -0,0 +1,316 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+	buildEnvOverrides,
+	buildNodeArgs,
+	buildBunArgs,
+	createNodeRuntimeManifestFile,
+	createLaunchPlan,
+	detectRuntime,
+	launchPlanRequiresExistingEntryFile,
+	resolveNodeRuntimeManifestPath,
+} from './launch-plan.js';
+
+const originalUserAgent = process.env.npm_config_user_agent;
+
+afterEach(() => {
+	if (originalUserAgent === undefined) {
+		delete process.env.npm_config_user_agent;
+	} else {
+		process.env.npm_config_user_agent = originalUserAgent;
+	}
+	process.chdir('/Users/andeeplus/github/ecopages');
+});
+
+describe('launch-plan', () => {
+	function writeExperimentalRuntimeConfig(tempDir) {
+		fs.writeFileSync(
+			path.join(tempDir, 'eco.config.ts'),
+			[
+				'const rootDir = process.cwd();',
+				'export default {',
+				'\trootDir,',
+				'\tloaders: new Map(),',
+				'\tabsolutePaths: {',
+				'\t\tconfig: `${rootDir}/eco.config.ts`,',
+				'\t\tsrcDir: `${rootDir}/src`,',
+				'\t\tdistDir: `${rootDir}/dist`,',
+				'\t\tworkDir: `${rootDir}/.eco`,',
+				'\t},',
+				'\truntime: {},',
+				'};',
+			].join('\n'),
+			'utf8',
+		);
+	}
+
+	function writeImportMetaRuntimeConfig(tempDir) {
+		fs.writeFileSync(
+			path.join(tempDir, 'eco.config.ts'),
+			[
+				"import path from 'node:path';",
+				'export default {',
+				'\trootDir: import.meta.dirname,',
+				'\tloaders: new Map(),',
+				'\tabsolutePaths: {',
+				"\t\tconfig: path.join(import.meta.dirname, 'eco.config.ts'),",
+				"\t\tsrcDir: path.join(import.meta.dirname, 'src'),",
+				"\t\tdistDir: path.join(import.meta.dirname, 'dist'),",
+				"\t\tworkDir: path.join(import.meta.dirname, '.eco'),",
+				'\t},',
+				'\truntime: {},',
+				'};',
+			].join('\n'),
+			'utf8',
+		);
+	}
+
+	it('buildEnvOverrides maps CLI options onto environment variables', () => {
+		expect(
+			buildEnvOverrides({
+				port: 4173,
+				hostname: '127.0.0.1',
+				baseUrl: 'https://example.test',
+				debug: true,
+				nodeEnv: 'production',
+			}),
+		).toEqual({
+			ECOPAGES_PORT: '4173',
+			ECOPAGES_HOSTNAME: '127.0.0.1',
+			ECOPAGES_BASE_URL: 'https://example.test',
+			ECOPAGES_LOGGER_DEBUG: 'true',
+			NODE_ENV: 'production',
+		});
+	});
+
+	it('detectRuntime defaults to node unless bun is explicit', () => {
+		process.env.npm_config_user_agent = 'pnpm/10.0.0 npm/? node/v24.0.0 darwin arm64';
+		expect(detectRuntime()).toBe('node');
+		expect(detectRuntime({ runtime: 'bun' })).toBe('bun');
+		expect(detectRuntime({ runtime: 'node' })).toBe('node');
+		expect(detectRuntime({ runtime: 'node-experimental' })).toBe('node-experimental');
+	});
+
+	it('buildNodeArgs preserves watch mode and fast refresh flags', () => {
+		expect(buildNodeArgs(['--dev'], { watch: true, reactFastRefresh: true }, 'app.ts')).toEqual([
+			'--watch',
+			expect.stringMatching(/node-thin-host\.js$/),
+			'app.ts',
+			'--dev',
+			'--react-fast-refresh',
+		]);
+	});
+
+	it('buildNodeArgs routes stable Node through the thin launcher', () => {
+		expect(buildNodeArgs(['--dev'], { watch: true }, 'app.ts')).toEqual([
+			'--watch',
+			expect.stringMatching(/node-thin-host\.js$/),
+			'app.ts',
+			'--dev',
+		]);
+	});
+
+	it('buildBunArgs preloads eco.config.ts when present', () => {
+		expect(buildBunArgs(['--dev'], { hot: true }, 'app.ts', true)).toEqual([
+			'--hot',
+			'run',
+			'--preload',
+			'eco.config.ts',
+			'app.ts',
+			'--dev',
+		]);
+	});
+
+	it('createLaunchPlan routes node app launches through the thin host', async () => {
+		const tempDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-cli-launch-plan-'));
+		try {
+			process.env.npm_config_user_agent = 'pnpm/10.0.0 npm/? node/v24.0.0 darwin arm64';
+			process.chdir(tempDir);
+			writeExperimentalRuntimeConfig(tempDir);
+			fs.writeFileSync(
+				path.join(tempDir, 'app.ts'),
+				[
+					"import { EcopagesApp } from '@ecopages/core';",
+					"import appConfig from './eco.config';",
+					'const app = new EcopagesApp({ appConfig });',
+					'await app.start();',
+				].join('\n'),
+				'utf8',
+			);
+			const plan = await createLaunchPlan(['--dev'], { watch: true, nodeEnv: 'development' }, 'app.ts');
+
+			expect(plan).toMatchObject({
+				runtime: 'node',
+				executionStrategy: 'node-thin-host',
+				command: 'node',
+				envOverrides: { NODE_ENV: 'development' },
+			});
+			expect(plan.commandArgs).toEqual([
+				'--watch',
+				expect.stringMatching(/node-thin-host\.js$/),
+				'app.ts',
+				'--dev',
+			]);
+		} finally {
+			fs.rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	it('createLaunchPlan preserves direct node entrypoints on the thin-host path', async () => {
+		const tempDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-cli-launch-plan-'));
+		try {
+			process.env.npm_config_user_agent = 'pnpm/10.0.0 npm/? node/v24.0.0 darwin arm64';
+			process.chdir(tempDir);
+			fs.writeFileSync(path.join(tempDir, 'server.ts'), 'await Promise.resolve();', 'utf8');
+			writeExperimentalRuntimeConfig(tempDir);
+
+			const plan = await createLaunchPlan(['--dev'], { watch: true }, 'server.ts');
+
+			expect(plan).toMatchObject({
+				runtime: 'node',
+				executionStrategy: 'node-thin-host',
+				command: 'node',
+			});
+			expect(plan.commandArgs).toEqual([
+				'--watch',
+				expect.stringMatching(/node-thin-host\.js$/),
+				'server.ts',
+				'--dev',
+			]);
+		} finally {
+			fs.rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	it('createLaunchPlan uses bun direct runtime and preloads eco.config.ts', async () => {
+		const tempDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-cli-launch-plan-'));
+		try {
+			process.chdir(tempDir);
+			fs.writeFileSync(path.join(tempDir, 'app.ts'), 'await Promise.resolve();', 'utf8');
+			writeExperimentalRuntimeConfig(tempDir);
+
+			const plan = await createLaunchPlan(['--preview'], { runtime: 'bun' }, 'app.ts');
+
+			expect(plan).toMatchObject({
+				runtime: 'bun',
+				executionStrategy: 'direct-runtime',
+				command: 'bun',
+			});
+			expect(plan.commandArgs).toEqual(['run', '--preload', 'eco.config.ts', 'app.ts', '--preview']);
+		} finally {
+			fs.rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	it('createNodeRuntimeManifestFile writes the core-owned manifest under .eco/runtime', async () => {
+		const tempDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-cli-launch-plan-'));
+		try {
+			process.chdir(tempDir);
+			writeExperimentalRuntimeConfig(tempDir);
+			const manifestFilePath = await createNodeRuntimeManifestFile('app.ts');
+			const manifest = JSON.parse(fs.readFileSync(manifestFilePath, 'utf8'));
+			const resolvedTempDir = fs.realpathSync(tempDir);
+
+			expect(manifestFilePath).toBe(resolveNodeRuntimeManifestPath(resolvedTempDir));
+			expect(manifest).toMatchObject({
+				runtime: 'node',
+				appRootDir: resolvedTempDir,
+				sourceRootDir: path.join(resolvedTempDir, 'src'),
+				distDir: path.join(resolvedTempDir, 'dist'),
+				workDir: path.join(resolvedTempDir, '.eco'),
+				modulePaths: {
+					config: path.join(resolvedTempDir, 'eco.config.ts'),
+					entry: path.join(resolvedTempDir, 'app.ts'),
+				},
+			});
+		} finally {
+			fs.rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	it('createNodeRuntimeManifestFile does not evaluate eco.config.ts while writing the manifest', async () => {
+		const tempDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-cli-launch-plan-'));
+		try {
+			process.chdir(tempDir);
+			writeImportMetaRuntimeConfig(tempDir);
+			const manifestFilePath = await createNodeRuntimeManifestFile('app.ts');
+			const manifest = JSON.parse(fs.readFileSync(manifestFilePath, 'utf8'));
+			const resolvedTempDir = fs.realpathSync(tempDir);
+
+			expect(manifestFilePath).toBe(resolveNodeRuntimeManifestPath(resolvedTempDir));
+			expect(manifest).toMatchObject({
+				appRootDir: resolvedTempDir,
+				sourceRootDir: path.join(resolvedTempDir, 'src'),
+				distDir: path.join(resolvedTempDir, 'dist'),
+				workDir: path.join(resolvedTempDir, '.eco'),
+				modulePaths: {
+					config: path.join(resolvedTempDir, 'eco.config.ts'),
+					entry: path.join(resolvedTempDir, 'app.ts'),
+				},
+			});
+		} finally {
+			fs.rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	it('createLaunchPlan routes node-experimental through the thin host launcher', async () => {
+		const tempDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-cli-launch-plan-'));
+		try {
+			process.chdir(tempDir);
+			writeExperimentalRuntimeConfig(tempDir);
+			const resolvedTempDir = fs.realpathSync(tempDir);
+			const plan = await createLaunchPlan(
+				['--dev'],
+				{ runtime: 'node-experimental', nodeEnv: 'development' },
+				'app.ts',
+			);
+
+			expect(plan).toMatchObject({
+				runtime: 'node-experimental',
+				executionStrategy: 'node-thin-host',
+				command: 'node',
+				envOverrides: { NODE_ENV: 'development' },
+			});
+			expect(plan.commandArgs).toEqual([expect.stringMatching(/node-thin-host\.js$/), 'app.ts', '--dev']);
+			expect(plan.env.ECOPAGES_NODE_RUNTIME_MANIFEST_PATH).toBe(resolveNodeRuntimeManifestPath(resolvedTempDir));
+			expect(JSON.parse(fs.readFileSync(plan.env.ECOPAGES_NODE_RUNTIME_MANIFEST_PATH, 'utf8'))).toMatchObject({
+				runtime: 'node',
+				modulePaths: {
+					config: path.join(resolvedTempDir, 'eco.config.ts'),
+					entry: path.join(resolvedTempDir, 'app.ts'),
+				},
+			});
+		} finally {
+			fs.rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	it('launchPlanRequiresExistingEntryFile requires a concrete entry on every runtime path', async () => {
+		const tempDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-cli-launch-plan-'));
+		try {
+			process.env.npm_config_user_agent = 'pnpm/10.0.0 npm/? node/v24.0.0 darwin arm64';
+			process.chdir(tempDir);
+			fs.writeFileSync(path.join(tempDir, 'app.ts'), 'await Promise.resolve();', 'utf8');
+			writeExperimentalRuntimeConfig(tempDir);
+
+			const nodePlan = await createLaunchPlan(['--dev'], { nodeEnv: 'development' }, 'app.ts');
+			expect(nodePlan.executionStrategy).toBe('node-thin-host');
+			expect(launchPlanRequiresExistingEntryFile(nodePlan)).toBe(true);
+
+			fs.writeFileSync(path.join(tempDir, 'server.ts'), 'await Promise.resolve();', 'utf8');
+			const directNodePlan = await createLaunchPlan(['--dev'], { nodeEnv: 'development' }, 'server.ts');
+			expect(directNodePlan.executionStrategy).toBe('node-thin-host');
+			expect(launchPlanRequiresExistingEntryFile(directNodePlan)).toBe(true);
+
+			const bunPlan = await createLaunchPlan(['--dev'], { runtime: 'bun' }, 'app.ts');
+			expect(launchPlanRequiresExistingEntryFile(bunPlan)).toBe(true);
+
+			const experimentalNodePlan = await createLaunchPlan(['--dev'], { runtime: 'node-experimental' }, 'app.ts');
+			expect(launchPlanRequiresExistingEntryFile(experimentalNodePlan)).toBe(true);
+		} finally {
+			fs.rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+});

package/bin/node-thin-host.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs';
+import { Logger } from '@ecopages/logger';
+import { assertNodeRuntimeManifest, createNodeRuntimeAdapter } from '@ecopages/core/node/runtime-adapter';
+import { fileURLToPath } from 'node:url';
+
+const logger = new Logger('[ecopages:node-thin-host]');
+
+function formatErrorForLog(error) {
+	if (error instanceof Error) {
+		return error.stack ?? error.message;
+	}
+
+	return String(error);
+}
+
+function attachShutdownHandlers(session) {
+	let shutdownPromise;
+
+	const shutdown = async (signal) => {
+		if (!shutdownPromise) {
+			shutdownPromise = (async () => {
+				try {
+					logger.info(`Received ${signal}. Shutting down Node thin-host runtime.`);
+					await session.dispose();
+				} catch (error) {
+					logger.error(formatErrorForLog(error));
+				} finally {
+					process.exit(0);
+				}
+			})();
+		}
+
+		await shutdownPromise;
+	};
+
+	process.once('SIGINT', () => {
+		void shutdown('SIGINT');
+	});
+	process.once('SIGTERM', () => {
+		void shutdown('SIGTERM');
+	});
+}
+
+/**
+ * Creates the host-to-adapter handoff payload for the Node thin-host runtime.
+ */
+export function createRuntimeStartOptions(options = {}) {
+	return {
+		manifest: options.manifest ?? readRuntimeManifest(),
+		workingDirectory: options.workingDirectory ?? process.cwd(),
+		cliArgs: options.cliArgs ?? process.argv.slice(2),
+	};
+}
+
+export function readRuntimeManifest() {
+	const manifestFilePath = process.env.ECOPAGES_NODE_RUNTIME_MANIFEST_PATH;
+
+	if (!manifestFilePath) {
+		throw new Error('Missing ECOPAGES_NODE_RUNTIME_MANIFEST_PATH for Node thin-host launch.');
+	}
+
+	let serializedManifest;
+
+	try {
+		serializedManifest = readFileSync(manifestFilePath, 'utf8');
+	} catch (error) {
+		throw new Error(
+			`Failed to read ECOPAGES_NODE_RUNTIME_MANIFEST_PATH at ${manifestFilePath}: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+
+	let parsedManifest;
+
+	try {
+		parsedManifest = JSON.parse(serializedManifest);
+	} catch (error) {
+		throw new Error(
+			`Invalid Node runtime manifest JSON: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+
+	return assertNodeRuntimeManifest(parsedManifest);
+}
+
+/**
+ * Starts the Node thin-host runtime by delegating validated input to the
+ * adapter boundary.
+ *
+ * @remarks
+ * This function intentionally keeps the thin host transport-oriented. It does
+ * not own framework bootstrap policy beyond reading the manifest, creating the
+ * adapter, and delegating startup plus shutdown lifecycle.
+ */
+export async function startThinHostRuntime(options = {}) {
+	const adapter = options.adapter ?? createNodeRuntimeAdapter();
+	const startOptions = createRuntimeStartOptions(options);
+	const session = await adapter.start(startOptions);
+	let loadedAppRuntime;
+
+	try {
+		loadedAppRuntime = await session.loadApp();
+	} catch (error) {
+		try {
+			await session.dispose();
+		} catch (disposeError) {
+			throw new Error(
+				`Failed to dispose Node thin-host runtime session after bootstrap error: ${disposeError instanceof Error ? disposeError.message : String(disposeError)}`,
+				{ cause: error instanceof Error ? error : undefined },
+			);
+		}
+
+		throw error;
+	}
+
+	if (options.attachShutdownHandlers !== false) {
+		attachShutdownHandlers(session);
+	}
+
+	return {
+		session,
+		loadedAppRuntime,
+	};
+}
+
+async function main() {
+	try {
+		await startThinHostRuntime();
+	} catch (error) {
+		logger.error(formatErrorForLog(error));
+		process.exit(1);
+	}
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	await main();
+}

package/bin/node-thin-host.test.ts

@@ -0,0 +1,167 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createRuntimeStartOptions, readRuntimeManifest, startThinHostRuntime } from './node-thin-host.js';
+
+const originalManifestPath = process.env.ECOPAGES_NODE_RUNTIME_MANIFEST_PATH;
+
+afterEach(() => {
+	if (originalManifestPath === undefined) {
+		delete process.env.ECOPAGES_NODE_RUNTIME_MANIFEST_PATH;
+	} else {
+		process.env.ECOPAGES_NODE_RUNTIME_MANIFEST_PATH = originalManifestPath;
+	}
+});
+
+describe('node-thin-host', () => {
+	it('reads, validates, and returns the runtime manifest from the file handoff', () => {
+		const tempDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-node-thin-host-'));
+		const manifestFilePath = path.join(tempDir, 'node-runtime-manifest.json');
+
+		try {
+			fs.writeFileSync(
+				manifestFilePath,
+				JSON.stringify({
+					runtime: 'node',
+					appRootDir: '/repo',
+					sourceRootDir: '/repo/src',
+					distDir: '/repo/dist',
+					workDir: '/repo/.eco',
+					modulePaths: {
+						config: '/repo/eco.config.ts',
+						entry: '/repo/app.ts',
+					},
+				}),
+				'utf8',
+			);
+
+			process.env.ECOPAGES_NODE_RUNTIME_MANIFEST_PATH = manifestFilePath;
+
+			expect(readRuntimeManifest()).toMatchObject({
+				modulePaths: {
+					entry: '/repo/app.ts',
+				},
+			});
+		} finally {
+			fs.rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	it('creates the adapter handoff from validated manifest plus process launch context', () => {
+		const manifest = {
+			runtime: 'node',
+			appRootDir: '/repo',
+			sourceRootDir: '/repo/src',
+			distDir: '/repo/dist',
+			workDir: '/repo/.eco',
+			modulePaths: {
+				config: '/repo/eco.config.ts',
+				entry: '/repo/app.ts',
+			},
+		};
+
+		expect(
+			createRuntimeStartOptions({
+				manifest,
+				workingDirectory: '/repo',
+				cliArgs: ['app.ts', '--dev'],
+			}),
+		).toEqual({
+			manifest,
+			workingDirectory: '/repo',
+			cliArgs: ['app.ts', '--dev'],
+		});
+	});
+
+	it('delegates startup to the adapter boundary and returns the loaded runtime session', async () => {
+		const session = {
+			loadApp: vi.fn(async () => ({
+				manifest: { runtime: 'node' },
+				workingDirectory: '/repo',
+				appConfig: { rootDir: '/repo' },
+				entryModulePath: '/repo/app.ts',
+				entryModule: { default: true },
+			})),
+			dispose: vi.fn(async () => undefined),
+		};
+		const adapter = {
+			start: vi.fn(async () => session),
+		};
+		const manifest = {
+			runtime: 'node',
+			appRootDir: '/repo',
+			sourceRootDir: '/repo/src',
+			distDir: '/repo/dist',
+			workDir: '/repo/.eco',
+			modulePaths: {
+				config: '/repo/eco.config.ts',
+				entry: '/repo/app.ts',
+			},
+		};
+
+		const runtime = await startThinHostRuntime({
+			adapter,
+			manifest,
+			workingDirectory: '/repo',
+			cliArgs: ['app.ts', '--dev'],
+			attachShutdownHandlers: false,
+		});
+
+		expect(adapter.start).toHaveBeenCalledWith({
+			manifest,
+			workingDirectory: '/repo',
+			cliArgs: ['app.ts', '--dev'],
+		});
+		expect(session.loadApp).toHaveBeenCalledTimes(1);
+		expect(runtime).toMatchObject({
+			loadedAppRuntime: {
+				entryModulePath: '/repo/app.ts',
+				appConfig: { rootDir: '/repo' },
+			},
+			session,
+		});
+	});
+
+	it('disposes the runtime session if app bootstrap fails after adapter startup', async () => {
+		const bootstrapError = new Error('bootstrap failed');
+		const session = {
+			loadApp: vi.fn(async () => {
+				throw bootstrapError;
+			}),
+			dispose: vi.fn(async () => undefined),
+		};
+		const adapter = {
+			start: vi.fn(async () => session),
+		};
+		const manifest = {
+			runtime: 'node',
+			appRootDir: '/repo',
+			sourceRootDir: '/repo/src',
+			distDir: '/repo/dist',
+			workDir: '/repo/.eco',
+			modulePaths: {
+				config: '/repo/eco.config.ts',
+				entry: '/repo/app.ts',
+			},
+		};
+
+		await expect(
+			startThinHostRuntime({
+				adapter,
+				manifest,
+				workingDirectory: '/repo',
+				cliArgs: ['app.ts', '--dev'],
+				attachShutdownHandlers: false,
+			}),
+		).rejects.toThrow('bootstrap failed');
+
+		expect(adapter.start).toHaveBeenCalledWith({
+			manifest,
+			workingDirectory: '/repo',
+			cliArgs: ['app.ts', '--dev'],
+		});
+		expect(session.loadApp).toHaveBeenCalledTimes(1);
+		expect(session.dispose).toHaveBeenCalledTimes(1);
+	});
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ecopages",
-  "version": "0.2.0-alpha.5",
+  "version": "0.2.0-alpha.6",
   "description": "CLI utilities for Ecopages",
   "type": "module",
   "license": "MIT",
@@ -34,6 +34,8 @@
     "README.md"
   ],
   "dependencies": {
+    "@ecopages/core": "workspace:*",
+    "esbuild": "^0.27.3",
     "commander": "^12.1.0",
     "tiged": "^2.12.7",
     "@ecopages/logger": "^0.2.2"