ecopages 0.2.0-alpha.9 → 0.2.0-beta.1

package/README.md

@@ -2,7 +2,7 @@
 
 The official CLI for the Ecopages framework.
 
-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`.
+It provides scaffolding and development commands to streamline your workflow. It prefers Bun when available, falls back to Node otherwise, and applies runtime-specific launch behavior for each engine.
 
 ## Quick Start
 
@@ -17,15 +17,15 @@ bun dev
 
 ## 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                                | 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`     |
 
 > [!NOTE]
 > `[entry]` defaults to `app.ts` if not provided.
@@ -34,27 +34,23 @@ bun dev
 
 Server and build commands accept the following options. They automatically map to the equivalent environment variables for the underlying process:
 
-| 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                     | 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` |
 
 ### Runtime Detection
 
-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.
-
-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.
+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.
 
 You can explicitly force the engine using the `--runtime` flag:
 
 ```bash
-ecopages dev --runtime node
 ecopages build --runtime bun
-ecopages dev --runtime node-experimental
 ```
 
 ### Example Usage
@@ -69,13 +65,7 @@ ecopages dev -r
 
 ## Ecosystem & Plugins
 
-Ecopages relies on a modular architecture. Core logic and framework integrations are published separately to [JSR](https://jsr.io/@ecopages).
-
-Configure your project to use JSR by adding a `.npmrc` file:
-
-```ini
-@jsr:registry=https://npm.jsr.io
-```
+Ecopages relies on a modular architecture. Core logic and framework integrations are published as `@ecopages/*` packages on [npm](https://www.npmjs.com/org/ecopages).
 
 ### Official Packages
 
@@ -84,6 +74,7 @@ Configure your project to use JSR by adding a `.npmrc` file:
 | `@ecopages/browser-router`    | Client-side navigation & view transitions. |
 | `@ecopages/codemod`           | AST migrations for codebase upgrades.      |
 | `@ecopages/core`              | The foundational SSG engine.               |
+| `@ecopages/ecopages-jsx`      | Ecopages-owned JSX routes and hydration.   |
 | `@ecopages/file-system`       | Runtime-agnostic file system utilities.    |
 | `@ecopages/image-processor`   | Asset pipeline for responsive images.      |
 | `@ecopages/kitajs`            | Integration for KitaJS.                    |
@@ -93,7 +84,7 @@ Configure your project to use JSR by adding a `.npmrc` file:
 | `@ecopages/react`             | Integration for React 19 SSR/Islands.      |
 | `@ecopages/react-router`      | SPA routing for React.                     |
 
-Explore all packages at [jsr.io/@ecopages](https://jsr.io/@ecopages).
+Explore all packages at [npmjs.com/org/ecopages](https://www.npmjs.com/org/ecopages).
 
 ## License
 

package/bin/cli.js

@@ -1,169 +1,335 @@
 #!/usr/bin/env node
-
-import { Command } from 'commander';
-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 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);
-	}
+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"
+  }
+};
+const initOptionDefinitions = {
+  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");
+}
+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");
+}
+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");
+}
+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");
+}
+function parseCommandArguments(rawArgs, options) {
+  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 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"
+  };
 }
-
-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);
-
 function runLaunchPlan(launchPlan) {
-	if (Object.keys(launchPlan.envOverrides).length > 0) {
-		logger.info(`Environment overrides: ${JSON.stringify(launchPlan.envOverrides)}`);
-	}
-
-	logger.info(`Runtime: ${launchPlan.runtime}`);
-	logger.info(`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.command === 'bun'
-					? 'Install Bun from https://bun.sh 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);
-		}
-
-		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);
+}
+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);
+  }
+}
+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
+  );
+}
+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);
+  }
 }
-
-/**
- * Execute a bun command with the given arguments and options.
- * 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
- */
-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);
-	}
-
-	runLaunchPlan(launchPlan);
+if (!process.env.VITEST) {
+  runCli();
 }
-
-/**
- * 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, node, or node-experimental)');
-
-serverOptions(
-	program.command('dev').description('Start the development server').argument('[entry]', 'Entry file', 'app.ts'),
-).action(async (entry, opts) => {
-	await runBunCommand(['--dev'], { ...opts, nodeEnv: 'development' }, entry);
-});
-
-serverOptions(
-	program
-		.command('dev:watch')
-		.description('Start the development server with watch mode (restarts on file changes)')
-		.argument('[entry]', 'Entry file', 'app.ts'),
-).action(async (entry, opts) => {
-	await runBunCommand(['--dev'], { ...opts, watch: true, nodeEnv: 'development' }, entry);
-});
-
-serverOptions(
-	program
-		.command('dev:hot')
-		.description('Start the development server with hot reload (HMR without restart)')
-		.argument('[entry]', 'Entry file', 'app.ts'),
-).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, 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(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(async (entry, opts) => {
-	await runBunCommand(['--preview'], { ...opts, nodeEnv: 'production' }, entry);
-});
-
-program.parse();
+export {
+  runCli
+};