ecopages 0.2.0-alpha.1 → 0.2.0-alpha.11

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 prefers Bun when available, falls back to Node otherwise, 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,81 @@ bun install
 bun dev
 ```
 
-## CLI Utilities
+## Commands
 
-### Commands
+| Command                      | Description                                | Equivalent (Bun)                |
+| :--------------------------- | :----------------------------------------- | :------------------------------ |
+| `ecopages init <dir>`        | Scaffolds a new project                    | N/A                             |
+| `ecopages dev [entry]`       | Starts the dev server                      | `bun run [entry] --dev`         |
+| `ecopages dev:watch [entry]` | Dev server + hard restarts on file changes | `bun --watch run [entry] --dev` |
+| `ecopages dev:hot [entry]`   | Dev server + HMR (no hard restarts)        | `bun --hot run [entry] --dev`   |
+| `ecopages build [entry]`     | Creates a production build                 | `bun run [entry] --build`       |
+| `ecopages start [entry]`     | Starts the production server               | `bun run [entry]`               |
+| `ecopages preview [entry]`   | Previews the production build locally      | `bun run [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` or `node` |
 
-| 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 prefers Bun when the package manager already indicates Bun, when the `Bun` global is available, or when you force it with `--runtime bun`. Otherwise it falls back to Node.
 
-```bash
-# Start dev server on port 8080 with debug logging
-ecopages dev --port 8080 --debug
-
-# 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 build --runtime bun
 ```
 
-## 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
+## Ecosystem & Plugins
 
-| Package                    | Description                                               | JSR Link                                       |
-| :------------------------- | :-------------------------------------------------------- | :--------------------------------------------- |
-| `@ecopages/browser-router` | Client-side navigation and view transitions for Ecopages. | [JSR](https://jsr.io/@ecopages/browser-router) |
+Ecopages relies on a modular architecture. Core logic and framework integrations are published separately to [JSR](https://jsr.io/@ecopages).
 
-| `@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) |
-
-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

@@ -1,169 +1,24 @@
 #!/usr/bin/env node
 
-import { Command } from 'commander';
+import { defineCommand, runMain } from 'citty';
+import { downloadTemplate } from 'giget';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 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]');
+const logger = new Logger('[ecopages:cli]', { debug: process.env.ECOPAGES_LOGGER_DEBUG === 'true' });
 
-const program = new Command();
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
 
-program.name('ecopages').description('Ecopages CLI utilities').version(pkg.version);
-
-async function handleInit(dir, opts) {
-	const { template, repo } = opts;
-	const targetDir = dir;
-
-	if (existsSync(targetDir)) {
-		logger.error(`Target directory already exists: ${targetDir}`);
-		process.exit(1);
-	}
-
-	logger.info(`Creating target directory '${targetDir}'...`);
-
-	try {
-		const emitter = tiged(`${repo}/examples/${template}`, {
-			disableCache: true,
-			force: true,
-			verbose: false,
-		});
-
-		await emitter.clone(targetDir);
-
-		const pkgPath = join(targetDir, '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 (err) {
-		logger.error(`Failed to fetch template: ${err.message}`);
-		process.exit(1);
-	}
-}
-
-program
-	.command('init <dir>')
-	.description('Initialize a new project from a template')
-	.option('--template <name>', 'Template name from ecopages/examples/', 'starter-jsx')
-	.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)}`);
+		logger.debug(`Environment overrides: ${JSON.stringify(launchPlan.envOverrides)}`);
 	}
 
-	logger.info(`Runtime: ${launchPlan.runtime}`);
-	logger.info(`Running: ${launchPlan.command} ${launchPlan.commandArgs.join(' ')}`);
+	logger.debug(`Runtime: ${launchPlan.runtime}`);
+	logger.debug(`Running: ${launchPlan.command} ${launchPlan.commandArgs.join(' ')}`);
 
 	const child = spawn(launchPlan.command, launchPlan.commandArgs, {
 		stdio: 'inherit',
@@ -173,9 +28,9 @@ function runLaunchPlan(launchPlan) {
 	child.on('error', (error) => {
 		if (error && error.code === 'ENOENT') {
 			const hint =
-				launchPlan.command === 'bun'
+				launchPlan.runtime === 'bun'
 					? 'Install Bun from https://bun.sh to continue.'
-					: 'Install tsx (`npm i -g tsx` or add it as a devDependency) to continue.';
+					: 'Reinstall ecopages and its dependencies so the packaged tsx runtime is available for Node.js launches.';
 			logger.error(`Command not found: ${launchPlan.command}. ${hint}`);
 			process.exit(1);
 		}
@@ -190,79 +45,216 @@ function runLaunchPlan(launchPlan) {
 }
 
 /**
- * Execute a bun command with the given arguments and options.
+ * Launch the entry file via the detected or forced runtime (bun or node).
  * Automatically detects eco.config.ts and applies preloads.
  * @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
  */
-function runBunCommand(args, options = {}, entryFile = 'app.ts') {
-	if (!existsSync(entryFile)) {
+async function runEntryCommand(args, options = {}, entryFile = 'app.ts') {
+	let launchPlan;
+
+	try {
+		launchPlan = await createLaunchPlan(args, options, entryFile);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		logger.error(message);
+		process.exit(1);
+	}
+
+	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);
 }
 
-/**
- * Add shared server options to a command.
- * @param {import('commander').Command} cmd - The command to add options to
- * @returns {import('commander').Command} The command with options added
- */
-const serverOptions = (cmd) =>
-	cmd
-		.option('-p, --port <port>', 'Override ECOPAGES_PORT')
-		.option('-n, --hostname <hostname>', 'Override ECOPAGES_HOSTNAME')
-		.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)');
+/** Shared server argument definitions for citty commands. */
+const serverArgs = {
+	entry: {
+		type: 'positional',
+		description: 'Entry file',
+		default: 'app.ts',
+	},
+	port: {
+		type: 'string',
+		alias: ['p'],
+		description: 'Override ECOPAGES_PORT',
+	},
+	hostname: {
+		type: 'string',
+		alias: ['n'],
+		description: 'Override ECOPAGES_HOSTNAME',
+	},
+	'base-url': {
+		type: 'string',
+		alias: ['b'],
+		description: 'Override ECOPAGES_BASE_URL',
+	},
+	debug: {
+		type: 'boolean',
+		alias: ['d'],
+		description: 'Enable debug logging (ECOPAGES_LOGGER_DEBUG=true)',
+	},
+	'react-fast-refresh': {
+		type: 'boolean',
+		alias: ['r'],
+		description: 'Enable React Fast Refresh for HMR',
+	},
+	runtime: {
+		type: 'string',
+		description: 'Force a specific runtime (bun or node)',
+	},
+};
+
+const initCommand = defineCommand({
+	meta: {
+		name: 'init',
+		description: 'Initialize a new project from a template',
+	},
+	args: {
+		dir: {
+			type: 'positional',
+			description: 'Target directory name',
+			required: true,
+		},
+		template: {
+			type: 'string',
+			description: 'Template name from ecopages/examples/',
+			default: 'starter-jsx',
+		},
+		repo: {
+			type: 'string',
+			description: 'GitHub repo (user/repo)',
+			default: 'ecopages/ecopages',
+		},
+	},
+	async run({ args }) {
+		const { dir, template, repo } = args;
+
+		if (existsSync(dir)) {
+			logger.error(`Target directory already exists: ${dir}`);
+			process.exit(1);
+		}
 
-serverOptions(
-	program.command('dev').description('Start the development server').argument('[entry]', 'Entry file', 'app.ts'),
-).action((entry, opts) => {
-	runBunCommand(['--dev'], { ...opts, nodeEnv: 'development' }, entry);
+		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 (err) {
+			logger.error(`Failed to fetch template: ${err.message}`);
+			process.exit(1);
+		}
+	},
 });
 
-serverOptions(
-	program
-		.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);
+const devCommand = defineCommand({
+	meta: {
+		name: 'dev',
+		description: 'Start the development server',
+	},
+	args: serverArgs,
+	async run({ args }) {
+		await runEntryCommand(['--dev'], { ...args, nodeEnv: 'development' }, args.entry);
+	},
 });
 
-serverOptions(
-	program
-		.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);
+const devWatchCommand = defineCommand({
+	meta: {
+		name: 'dev:watch',
+		description: 'Start the development server with watch mode (restarts on file changes)',
+	},
+	args: serverArgs,
+	async run({ args }) {
+		await runEntryCommand(['--dev'], { ...args, watch: true, nodeEnv: 'development' }, args.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);
-	});
+const devHotCommand = defineCommand({
+	meta: {
+		name: 'dev:hot',
+		description: 'Start the development server with hot reload (HMR without restart)',
+	},
+	args: serverArgs,
+	async run({ args }) {
+		await runEntryCommand(['--dev'], { ...args, hot: true, nodeEnv: 'development' }, args.entry);
+	},
+});
+
+const buildCommand = defineCommand({
+	meta: {
+		name: 'build',
+		description: 'Build the project for production',
+	},
+	args: {
+		entry: {
+			type: 'positional',
+			description: 'Entry file',
+			default: 'app.ts',
+		},
+		runtime: {
+			type: 'string',
+			description: 'Force a specific runtime (bun or node)',
+		},
+	},
+	async run({ args }) {
+		await runEntryCommand(['--build'], { nodeEnv: 'production', ...args }, args.entry);
+	},
+});
+
+const startCommand = defineCommand({
+	meta: {
+		name: 'start',
+		description: 'Start the production server',
+	},
+	args: serverArgs,
+	async run({ args }) {
+		await runEntryCommand([], { ...args, nodeEnv: 'production' }, args.entry);
+	},
+});
 
-serverOptions(
-	program.command('start').description('Start the production server').argument('[entry]', 'Entry file', 'app.ts'),
-).action((entry, opts) => {
-	runBunCommand([], { ...opts, nodeEnv: 'production' }, entry);
+const previewCommand = defineCommand({
+	meta: {
+		name: 'preview',
+		description: 'Preview the production build',
+	},
+	args: serverArgs,
+	async run({ args }) {
+		await runEntryCommand(['--preview'], { ...args, nodeEnv: 'production' }, args.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);
+export const mainCommand = defineCommand({
+	meta: {
+		name: 'ecopages',
+		version: pkg.version,
+		description: 'Ecopages CLI utilities',
+	},
+	subCommands: {
+		init: initCommand,
+		dev: devCommand,
+		'dev:watch': devWatchCommand,
+		'dev:hot': devHotCommand,
+		build: buildCommand,
+		start: startCommand,
+		preview: previewCommand,
+	},
 });
 
-program.parse();
+if (!process.env.VITEST) {
+	runMain(mainCommand);
+}

package/bin/cli.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { runCommand } from 'citty';
+import { mainCommand } from './cli.js';
+import * as giget from 'giget';
+import * as fs from 'node:fs';
+import * as launchPlan from './launch-plan.js';
+
+vi.mock('giget', () => ({
+	downloadTemplate: vi.fn(),
+}));
+
+vi.mock('node:fs', async (importOriginal) => {
+	const actual = await importOriginal<typeof import('node:fs')>();
+	return {
+		...actual,
+		existsSync: vi.fn((path) => actual.existsSync(path)),
+		writeFileSync: vi.fn(),
+	};
+});
+
+vi.mock('./launch-plan.js', () => ({
+	createLaunchPlan: vi.fn(),
+	launchPlanRequiresExistingEntryFile: vi.fn(),
+}));
+
+vi.mock('node:child_process', () => ({
+	spawn: vi.fn().mockImplementation(() => ({
+		on: vi.fn(),
+	})),
+}));
+
+vi.mock('@ecopages/logger', () => ({
+	Logger: class {
+		info = vi.fn();
+		warn = vi.fn();
+		error = vi.fn();
+		debug = vi.fn();
+	},
+}));
+
+describe('CLI Commands', () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+
+		// Default mocks
+		vi.mocked(fs.existsSync).mockReturnValue(false); // pretend no existing dir
+		vi.mocked(launchPlan.createLaunchPlan).mockResolvedValue({
+			runtime: 'node',
+			command: 'node',
+			commandArgs: [],
+			envOverrides: {},
+			env: {},
+		} as any);
+		vi.mocked(launchPlan.launchPlanRequiresExistingEntryFile).mockReturnValue(false);
+	});
+
+	it('runs init command with default template and repo', async () => {
+		await runCommand(mainCommand, { rawArgs: ['init', 'my-new-project'] });
+		expect(giget.downloadTemplate).toHaveBeenCalledWith('github:ecopages/ecopages/examples/starter-jsx', {
+			dir: 'my-new-project',
+			force: true,
+		});
+	});
+
+	it('runs init command with custom template and repo', async () => {
+		await runCommand(mainCommand, {
+			rawArgs: ['init', 'my-dir', '--template', 'starter-lit', '--repo', 'custom/repo'],
+		});
+		expect(giget.downloadTemplate).toHaveBeenCalledWith('github:custom/repo/examples/starter-lit', {
+			dir: 'my-dir',
+			force: true,
+		});
+	});
+
+	it('runs dev command and passes defaults to launch plan', async () => {
+		await runCommand(mainCommand, { rawArgs: ['dev'] });
+		expect(launchPlan.createLaunchPlan).toHaveBeenCalledWith(
+			['--dev'],
+			expect.objectContaining({ nodeEnv: 'development' }),
+			'app.ts',
+		);
+	});
+
+	it('runs dev:hot command', async () => {
+		await runCommand(mainCommand, { rawArgs: ['dev:hot'] });
+		expect(launchPlan.createLaunchPlan).toHaveBeenCalledWith(
+			['--dev'],
+			expect.objectContaining({ hot: true, nodeEnv: 'development' }),
+			'app.ts',
+		);
+	});
+
+	it('runs dev:watch command', async () => {
+		await runCommand(mainCommand, { rawArgs: ['dev:watch'] });
+		expect(launchPlan.createLaunchPlan).toHaveBeenCalledWith(
+			['--dev'],
+			expect.objectContaining({ watch: true, nodeEnv: 'development' }),
+			'app.ts',
+		);
+	});
+
+	it('runs build command with custom entry file', async () => {
+		await runCommand(mainCommand, { rawArgs: ['build', 'server.ts'] });
+		expect(launchPlan.createLaunchPlan).toHaveBeenCalledWith(
+			['--build'],
+			expect.objectContaining({ nodeEnv: 'production' }),
+			'server.ts',
+		);
+	});
+
+	it('passes shared server options like port and hostname correctly', async () => {
+		await runCommand(mainCommand, { rawArgs: ['start', '-p', '4000', '--hostname', '0.0.0.0'] });
+		expect(launchPlan.createLaunchPlan).toHaveBeenCalledWith(
+			[],
+			expect.objectContaining({
+				nodeEnv: 'production',
+				port: '4000',
+				hostname: '0.0.0.0',
+			}),
+			'app.ts',
+		);
+	});
+
+	it('allows overriding base url and debug options', async () => {
+		await runCommand(mainCommand, { rawArgs: ['preview', '--base-url', '/my-app/', '-d'] });
+		expect(launchPlan.createLaunchPlan).toHaveBeenCalledWith(
+			['--preview'],
+			expect.objectContaining({
+				nodeEnv: 'production',
+				'base-url': '/my-app/',
+				debug: true,
+			}),
+			'app.ts',
+		);
+	});
+});

package/bin/launch-plan.js

@@ -0,0 +1,112 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+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') {
+		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, hasConfig) {
+	const nodeArgs = [];
+
+	if (hasConfig) {
+		nodeArgs.push('--import', './eco.config.ts');
+	}
+
+	nodeArgs.push(entryFile, ...args);
+
+	if (options.reactFastRefresh) {
+		nodeArgs.push('--react-fast-refresh');
+	}
+
+	return nodeArgs;
+}
+
+export function resolveTsxCliPath() {
+	try {
+		return require.resolve('tsx/cli');
+	} catch {
+		throw new Error(
+			'Unable to resolve the packaged tsx runtime required for Node.js launches. Reinstall ecopages and its dependencies, or use the Bun runtime instead.',
+		);
+	}
+}
+
+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') {
+		const tsxCliPath = resolveTsxCliPath();
+
+		return {
+			runtime,
+			executionStrategy: 'direct-runtime',
+			command: process.execPath,
+			commandArgs: [tsxCliPath, ...buildNodeArgs(args, options, entryFile, hasConfig)],
+			envOverrides,
+			env,
+		};
+	}
+
+	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,160 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+	buildEnvOverrides,
+	buildBunArgs,
+	buildNodeArgs,
+	createLaunchPlan,
+	detectRuntime,
+	launchPlanRequiresExistingEntryFile,
+	resolveTsxCliPath,
+} from './launch-plan.js';
+
+const require = createRequire(import.meta.url);
+
+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',
+		);
+	}
+
+	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 returns node when Bun is not available', () => {
+		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');
+	});
+
+	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('buildNodeArgs imports eco.config.ts when present', () => {
+		expect(buildNodeArgs(['--dev'], {}, 'app.ts', true)).toEqual([
+			'--import',
+			'./eco.config.ts',
+			'app.ts',
+			'--dev',
+		]);
+	});
+
+	it('resolveTsxCliPath resolves the packaged tsx cli entry', () => {
+		expect(resolveTsxCliPath()).toBe(require.resolve('tsx/cli'));
+	});
+
+	it('createLaunchPlan uses the packaged tsx cli for node runtime', 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 plan = await createLaunchPlan(['--dev'], { runtime: 'node', nodeEnv: 'development' }, 'app.ts');
+
+			expect(plan).toMatchObject({
+				runtime: 'node',
+				executionStrategy: 'direct-runtime',
+				command: process.execPath,
+			});
+			expect(plan.commandArgs).toEqual([
+				require.resolve('tsx/cli'),
+				'--import',
+				'./eco.config.ts',
+				'app.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('launchPlanRequiresExistingEntryFile requires a concrete entry on every runtime path', 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 bunPlan = await createLaunchPlan(['--dev'], { nodeEnv: 'development' }, 'app.ts');
+			expect(launchPlanRequiresExistingEntryFile(bunPlan)).toBe(true);
+		} finally {
+			fs.rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ecopages",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0-alpha.11",
   "description": "CLI utilities for Ecopages",
   "type": "module",
   "license": "MIT",
@@ -8,7 +8,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ecopages/ecopages.git",
-    "directory": "npm/ecopages"
+    "directory": "packages/ecopages"
   },
   "homepage": "https://github.com/ecopages/ecopages#readme",
   "bugs": {
@@ -34,9 +34,11 @@
     "README.md"
   ],
   "dependencies": {
-    "commander": "^12.1.0",
-    "tiged": "^2.12.7",
-    "@ecopages/logger": "^0.2.2"
+    "@ecopages/core": "workspace:*",
+    "@ecopages/logger": "^0.2.2",
+    "citty": "^0.1.6",
+    "giget": "^2.0.0",
+    "tsx": "^4.21.0"
   },
   "peerDependencies": {
     "bun-types": "*",