ecopages 0.2.0-alpha.39 → 0.2.0-alpha.41

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 prefers Bun when available, falls back to Node otherwise, 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
 

package/bin/cli.js

@@ -1,13 +1,162 @@
 #!/usr/bin/env node
-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 { parseArgs } from "node:util";
 import { Logger } from "@ecopages/logger";
-import { createLaunchPlan, launchPlanRequiresExistingEntryFile } from "./launch-plan.js";
+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"
+  },
+  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 [entry]             Start the development server",
+    "  dev:watch [entry]       Start the development server with watch mode",
+    "  dev:hot [entry]         Start the development server with hot reload",
+    "  build [entry]           Build the project for production",
+    "  start [entry]           Start the production server",
+    "  preview [entry]         Preview the production build",
+    "",
+    "Global options:",
+    "  -h, --help              Show help",
+    "  --version               Show version"
+  ].join("\n");
+}
+function getServerCommandHelpText(commandName, description) {
+  return [
+    `Usage: ecopages ${commandName} [entry] [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",
+    "  -h, --help                              Show help"
+  ].join("\n");
+}
+function getBuildCommandHelpText() {
+  return [
+    "Usage: ecopages build [entry] [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",
+    "  -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 > 1) {
+    throw new Error(`Too many positional arguments provided for \`${commandName}\`.`);
+  }
+  return {
+    entry: positionals[0] ?? "app.ts",
+    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"
+  };
+}
 function runLaunchPlan(launchPlan) {
   if (Object.keys(launchPlan.envOverrides).length > 0) {
     logger.debug(`Environment overrides: ${JSON.stringify(launchPlan.envOverrides)}`);
@@ -40,185 +189,125 @@ async function runEntryCommand(args, options = {}, entryFile = "app.ts") {
     logger.error(message);
     process.exit(1);
   }
-  if (launchPlanRequiresExistingEntryFile(launchPlan) && !existsSync(entryFile)) {
+  if (!existsSync(entryFile)) {
     logger.error(`Error: Entry file "${entryFile}" not found in the current directory.`);
     process.exit(1);
   }
   runLaunchPlan(launchPlan);
 }
-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)"
+async function runInitCommand(rawArgs) {
+  const parsed = parseInitCommandArgs(rawArgs);
+  if (parsed.help) {
+    return;
   }
-};
-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);
-    }
-    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);
+  const { dir, template, repo } = parsed;
+  if (existsSync(dir)) {
+    logger.error(`Target directory already exists: ${dir}`);
+    process.exit(1);
+  }
+  logger.info(`Creating target directory '${dir}'...`);
+  try {
+    await downloadTemplate(`github:${repo}/examples/${template}`, {
+      dir,
+      force: true
+    });
+    const pkgPath = join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      const projectPkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+      projectPkg.name = dir;
+      writeFileSync(pkgPath, JSON.stringify(projectPkg, null, 2) + "\n");
+      logger.info(`Renamed project to '${dir}'`);
     }
+    logger.info("Project initialized! Run `bun install && bun dev` to start.");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.error(`Failed to fetch template: ${message}`);
+    process.exit(1);
   }
-});
-const devCommand = defineCommand({
-  meta: {
-    name: "dev",
-    description: "Start the development server"
-  },
-  args: serverArgs,
-  async run({ args }) {
-    await runEntryCommand(["--dev"], { ...args, nodeEnv: "development" }, args.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);
-  }
-});
-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 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 }, parsed.entry);
+}
+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"],
+          optionOverrides: { nodeEnv: "development" }
+        });
+        return;
+      case "dev:watch":
+        await runServerCommand(commandArgs, {
+          name: "dev:watch",
+          description: "Start the development server with watch mode.",
+          entryArgs: ["--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"],
+          optionOverrides: { hot: true, nodeEnv: "development" }
+        });
+        return;
+      case "build":
+        await runServerCommand(commandArgs, {
+          name: "build",
+          description: "Build the project for production.",
+          entryArgs: ["--build"],
+          optionOverrides: { nodeEnv: "production" },
+          mode: "build"
+        });
+        return;
+      case "start":
+        await runServerCommand(commandArgs, {
+          name: "start",
+          description: "Start the production server.",
+          entryArgs: [],
+          optionOverrides: { nodeEnv: "production" }
+        });
+        return;
+      case "preview":
+        await runServerCommand(commandArgs, {
+          name: "preview",
+          description: "Preview the production build.",
+          entryArgs: ["--preview"],
+          optionOverrides: { nodeEnv: "production" }
+        });
+        return;
+      default:
+        throw new Error(`Unknown command \`${commandName}\`.`);
     }
-  },
-  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);
-  }
-});
-const previewCommand = defineCommand({
-  meta: {
-    name: "preview",
-    description: "Preview the production build"
-  },
-  args: serverArgs,
-  async run({ args }) {
-    await runEntryCommand(["--preview"], { ...args, nodeEnv: "production" }, args.entry);
-  }
-});
-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
-  }
-});
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.error(message);
+    process.exit(1);
+  }
+}
 if (!process.env.VITEST) {
-  runMain(mainCommand);
+  runCli();
 }
 export {
-  mainCommand
+  runCli
 };

package/bin/launch-plan.js

@@ -1,6 +1,13 @@
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 const require2 = createRequire(import.meta.url);
+function buildNodeEnvFileArgs(nodeEnv) {
+  const envFiles = [".env", ".env.local"];
+  if (nodeEnv) {
+    envFiles.push(`.env.${nodeEnv}`, `.env.${nodeEnv}.local`);
+  }
+  return envFiles.filter((envFile) => existsSync(envFile)).map((envFile) => `--env-file=${envFile}`);
+}
 function buildEnvOverrides(options) {
   const env = {};
   if (options.port) env.ECOPAGES_PORT = String(options.port);
@@ -37,14 +44,6 @@ function buildBunArgs(args, options, entryFile, hasConfig) {
   }
   return bunArgs;
 }
-function buildNodeArgs(args, options, entryFile, _hasConfig) {
-  const nodeArgs = [];
-  nodeArgs.push(entryFile, ...args);
-  if (options.reactFastRefresh) {
-    nodeArgs.push("--react-fast-refresh");
-  }
-  return nodeArgs;
-}
 function resolveTsxCliPath() {
   try {
     return require2.resolve("tsx/cli");
@@ -55,39 +54,32 @@ function resolveTsxCliPath() {
   }
 }
 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();
+    const nodeArgs = [entryFile, ...args];
     return {
       runtime,
-      executionStrategy: "direct-runtime",
       command: process.execPath,
-      commandArgs: [tsxCliPath, ...buildNodeArgs(args, options, entryFile, hasConfig)],
+      commandArgs: [...buildNodeEnvFileArgs(options.nodeEnv), tsxCliPath, ...nodeArgs],
       envOverrides,
       env
     };
   }
   return {
     runtime,
-    executionStrategy: "direct-runtime",
     command: "bun",
-    commandArgs: buildBunArgs(args, options, entryFile, hasConfig),
+    commandArgs: buildBunArgs(args, options, entryFile, existsSync("eco.config.ts")),
     envOverrides,
     env
   };
 }
-function launchPlanRequiresExistingEntryFile(launchPlan) {
-  return launchPlan.executionStrategy !== "config-only-bootstrap";
-}
 export {
   buildBunArgs,
   buildEnvOverrides,
-  buildNodeArgs,
   createLaunchPlan,
   detectRuntime,
-  launchPlanRequiresExistingEntryFile,
   resolveTsxCliPath
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ecopages",
-  "version": "0.2.0-alpha.39",
+  "version": "0.2.0-alpha.41",
   "description": "CLI utilities for Ecopages",
   "type": "module",
   "license": "MIT",
@@ -29,9 +29,8 @@
     "ecopages": "bin/cli.js"
   },
   "dependencies": {
-    "@ecopages/core": "0.2.0-alpha.39",
+    "@ecopages/core": "0.2.0-alpha.41",
     "@ecopages/logger": "^0.2.3",
-    "citty": "^0.1.6",
     "giget": "^2.0.0",
     "tsx": "^4.22.0"
   },