ecopages 0.2.0-alpha.29 → 0.2.0-alpha.30

package/dist/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to `ecopages` are documented here.
+
+> **Note:** Changelog tracking begins at version `0.2.0`. Changes prior to this release are not recorded here but are available in the git history.
+
+## [UNRELEASED] — TBD
+
+### Bug Fixes
+
+- Localized the Node CLI `tsx` runtime dependency so `ecopages` no longer requires a globally installed `tsx` binary.
+
+### Refactoring
+
+- Simplified CLI runtime startup and removed the thin-host bootstrap path; runtime selection now follows explicit `--runtime` overrides, package-manager hints, and Bun availability.

package/dist/README.md

@@ -0,0 +1,91 @@
+# ecopages
+
+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`.
+
+## Quick Start
+
+Initialize a new project from the default template:
+
+```bash
+bunx ecopages init my-app
+cd my-app
+bun install
+bun dev
+```
+
+## 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`     |
+
+> [!NOTE]
+> `[entry]` defaults to `app.ts` if not provided.
+
+## Environment & Runtime Options
+
+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` or `node` |
+
+### Runtime Detection
+
+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 build --runtime bun
+```
+
+### Example Usage
+
+```bash
+# Debug dev server on custom port
+ecopages dev --port 8080 --debug
+
+# Dev server with React Fast Refresh enabled
+ecopages dev -r
+```
+
+## Ecosystem & Plugins
+
+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
+
+| Package                       | Description                                |
+| :---------------------------- | :----------------------------------------- |
+| `@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.                    |
+| `@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.                     |
+
+Explore all packages at [npmjs.com/org/ecopages](https://www.npmjs.com/org/ecopages).
+
+## License
+
+MIT

package/dist/bin/cli.js

@@ -0,0 +1,224 @@
+#!/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 { Logger } from "@ecopages/logger";
+import { createLaunchPlan, launchPlanRequiresExistingEntryFile } 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"));
+function runLaunchPlan(launchPlan) {
+  if (Object.keys(launchPlan.envOverrides).length > 0) {
+    logger.debug(`Environment overrides: ${JSON.stringify(launchPlan.envOverrides)}`);
+  }
+  logger.debug(`Runtime: ${launchPlan.runtime}`);
+  logger.debug(`Running: ${launchPlan.command} ${launchPlan.commandArgs.join(" ")}`);
+  const child = spawn(launchPlan.command, launchPlan.commandArgs, {
+    stdio: "inherit",
+    env: launchPlan.env
+  });
+  child.on("error", (error) => {
+    if (error && error.code === "ENOENT") {
+      const hint = launchPlan.runtime === "bun" ? "Install Bun from https://bun.sh to continue." : "Reinstall 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);
+    }
+    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") {
+  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);
+  }
+  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)"
+  }
+};
+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 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 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
+  }
+});
+if (!process.env.VITEST) {
+  runMain(mainCommand);
+}
+export {
+  mainCommand
+};

package/dist/bin/launch-plan.js

@@ -0,0 +1,96 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+const require2 = createRequire(import.meta.url);
+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 (userAgent.startsWith("bun/")) {
+    return "bun";
+  }
+  if (typeof Bun !== "undefined") {
+    return "bun";
+  }
+  return "node";
+}
+function buildBunArgs(args, options, entryFile, hasConfig) {
+  const bunArgs = [];
+  if (options.watch) bunArgs.push("--watch");
+  if (options.hot) bunArgs.push("--hot");
+  bunArgs.push("run");
+  if (hasConfig) {
+    bunArgs.push("--preload", "./eco.config.js");
+  }
+  bunArgs.push(entryFile, ...args);
+  if (options.reactFastRefresh) {
+    bunArgs.push("--react-fast-refresh");
+  }
+  return bunArgs;
+}
+function buildNodeArgs(args, options, entryFile, hasConfig) {
+  const nodeArgs = [];
+  if (hasConfig) {
+    nodeArgs.push("--import", "./eco.config.js");
+  }
+  nodeArgs.push(entryFile, ...args);
+  if (options.reactFastRefresh) {
+    nodeArgs.push("--react-fast-refresh");
+  }
+  return nodeArgs;
+}
+function resolveTsxCliPath() {
+  try {
+    return require2.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."
+    );
+  }
+}
+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
+  };
+}
+function launchPlanRequiresExistingEntryFile(launchPlan) {
+  return launchPlan.executionStrategy !== "config-only-bootstrap";
+}
+export {
+  buildBunArgs,
+  buildEnvOverrides,
+  buildNodeArgs,
+  createLaunchPlan,
+  detectRuntime,
+  launchPlanRequiresExistingEntryFile,
+  resolveTsxCliPath
+};

package/dist/css/view-transitions.css

@@ -0,0 +1,217 @@
+/**
+ * Default View Transition CSS for EcoPages
+ *
+ * Import this file in your CSS:
+ * @import 'ecopages/css/view-transitions.css';
+ *
+ * Works with both @ecopages/browser-router and @ecopages/react-router.
+ */
+
+/* Disable root animation to prevent full page flash during transitions */
+::view-transition-old(root),
+::view-transition-new(root) {
+	animation: none;
+}
+
+/* Shared element transitions animate position/size smoothly */
+::view-transition-group(*) {
+	animation-duration: 180ms;
+	animation-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+/* Prevent transitioning elements from affecting layout of non-transitioning elements */
+::view-transition-image-pair(*) {
+	isolation: isolate;
+}
+
+/* Respect reduced motion preference */
+@media (prefers-reduced-motion: reduce) {
+	::view-transition-group(*),
+	::view-transition-old(*),
+	::view-transition-new(*) {
+		animation: none !important;
+	}
+}
+
+@keyframes eco-fade-out {
+	from {
+		opacity: 1;
+	}
+	to {
+		opacity: 0;
+	}
+}
+
+@keyframes eco-fade-in {
+	from {
+		opacity: 0;
+	}
+	to {
+		opacity: 1;
+	}
+}
+
+/* Slide transition for elements with view-transition-name: eco-slide */
+::view-transition-image-pair(eco-slide) {
+	isolation: isolate;
+}
+
+::view-transition-old(eco-slide),
+::view-transition-new(eco-slide) {
+	animation-duration: 180ms;
+	animation-timing-function: ease-out;
+	mix-blend-mode: normal;
+}
+
+::view-transition-old(eco-slide) {
+	animation-name: eco-slide-out;
+}
+
+::view-transition-new(eco-slide) {
+	animation-name: eco-slide-in;
+}
+
+@keyframes eco-slide-out {
+	from {
+		opacity: 1;
+		transform: translateX(0);
+	}
+	to {
+		opacity: 0;
+		transform: translateX(-30px);
+	}
+}
+
+@keyframes eco-slide-in {
+	from {
+		opacity: 0;
+		transform: translateX(30px);
+	}
+	to {
+		opacity: 1;
+		transform: translateX(0);
+	}
+}
+
+/* Persistent elements should not animate */
+[data-eco-persist] {
+	view-transition-name: none;
+}
+
+/* Declarative transition attributes */
+[data-eco-transition='slide'] {
+	view-transition-name: eco-slide;
+}
+[data-eco-transition='fade'] {
+	view-transition-name: eco-fade;
+}
+[data-eco-transition='zoom'] {
+	view-transition-name: eco-zoom;
+}
+[data-eco-transition='slide-up'] {
+	view-transition-name: eco-slide-up;
+}
+[data-eco-transition='slide-down'] {
+	view-transition-name: eco-slide-down;
+}
+
+/* FADE */
+::view-transition-old(eco-fade) {
+	animation: eco-fade-out 180ms ease-out both;
+}
+::view-transition-new(eco-fade) {
+	animation: eco-fade-in 180ms ease-out both;
+}
+
+/* ZOOM */
+::view-transition-image-pair(eco-zoom) {
+	isolation: isolate;
+}
+::view-transition-old(eco-zoom) {
+	animation: eco-zoom-out 180ms ease-in both;
+}
+::view-transition-new(eco-zoom) {
+	animation: eco-zoom-in 180ms ease-out both;
+}
+@keyframes eco-zoom-out {
+	from {
+		opacity: 1;
+		transform: scale(1);
+	}
+	to {
+		opacity: 0;
+		transform: scale(0.9);
+	}
+}
+@keyframes eco-zoom-in {
+	from {
+		opacity: 0;
+		transform: scale(0.9);
+	}
+	to {
+		opacity: 1;
+		transform: scale(1);
+	}
+}
+
+/* SLIDE UP */
+::view-transition-image-pair(eco-slide-up) {
+	isolation: isolate;
+}
+::view-transition-old(eco-slide-up) {
+	animation: eco-slide-up-out 180ms ease-in both;
+}
+::view-transition-new(eco-slide-up) {
+	animation: eco-slide-up-in 180ms ease-out both;
+}
+@keyframes eco-slide-up-out {
+	from {
+		opacity: 1;
+		transform: translateY(0);
+	}
+	to {
+		opacity: 0;
+		transform: translateY(-30px);
+	}
+}
+@keyframes eco-slide-up-in {
+	from {
+		opacity: 0;
+		transform: translateY(30px);
+	}
+	to {
+		opacity: 1;
+		transform: translateY(0);
+	}
+}
+
+/* SLIDE DOWN */
+::view-transition-image-pair(eco-slide-down) {
+	isolation: isolate;
+}
+::view-transition-old(eco-slide-down) {
+	animation: eco-slide-down-out 180ms ease-in both;
+}
+::view-transition-new(eco-slide-down) {
+	animation: eco-slide-down-in 180ms ease-out both;
+}
+@keyframes eco-slide-down-out {
+	from {
+		opacity: 1;
+		transform: translateY(0);
+	}
+	to {
+		opacity: 0;
+		transform: translateY(30px);
+	}
+}
+@keyframes eco-slide-down-in {
+	from {
+		opacity: 0;
+		transform: translateY(-30px);
+	}
+	to {
+		opacity: 1;
+		transform: translateY(0);
+	}
+}

package/dist/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "ecopages",
+  "version": "0.2.0-alpha.30",
+  "description": "CLI utilities for Ecopages",
+  "type": "module",
+  "license": "MIT",
+  "author": "Ecopages Team",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ecopages/ecopages.git",
+    "directory": "packages/ecopages"
+  },
+  "homepage": "https://github.com/ecopages/ecopages#readme",
+  "bugs": {
+    "url": "https://github.com/ecopages/ecopages/issues"
+  },
+  "keywords": [
+    "ecopages",
+    "bun",
+    "web-framework",
+    "ssr",
+    "static-site-generator",
+    "react",
+    "kitajs",
+    "lit",
+    "mdx"
+  ],
+  "bin": {
+    "ecopages": "bin/cli.js"
+  },
+  "dependencies": {
+    "@ecopages/core": "0.2.0-alpha.30",
+    "@ecopages/logger": "^0.2.2",
+    "citty": "^0.1.6",
+    "giget": "^2.0.0",
+    "tsx": "^4.21.0"
+  },
+  "peerDependencies": {
+    "bun-types": "*",
+    "typescript": "^5"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ecopages",
-  "version": "0.2.0-alpha.29",
+  "version": "0.2.0-alpha.30",
   "description": "CLI utilities for Ecopages",
   "type": "module",
   "license": "MIT",
@@ -31,6 +31,7 @@
   "files": [
     "bin/",
     "css/",
+    "dist/",
     "README.md"
   ],
   "dependencies": {