@evjs/cli 0.0.1-rc.13

package/AGENT.md

@@ -0,0 +1,121 @@
+# @evjs/cli — Agent Guide
+
+> AI-agent reference for developing apps with the `@evjs/cli` package.
+
+## Overview
+
+`@evjs/cli` is the CLI and configuration layer. Users install it as a devDependency. It provides:
+
+- **`ev init`** — scaffold a new project from templates
+- **`ev dev`** — start dev server (webpack-dev-server + API server)
+- **`ev build`** — production build (client + server bundles)
+- **`defineConfig`** — type-safe config export for `ev.config.ts`
+
+## Quick Start
+
+```bash
+npx @evjs/cli@latest init my-app
+cd my-app && npm install
+ev dev     # http://localhost:3000
+```
+
+## Configuration (`ev.config.ts`)
+
+Optional — everything works zero-config. Create `ev.config.ts` in project root when needed:
+
+```ts
+import { defineConfig } from "@evjs/cli";
+
+export default defineConfig({
+  client: {
+    entry: "./src/main.tsx",           // default
+    html: "./index.html",              // default
+    dev: {
+      port: 3000,                      // webpack-dev-server port
+      open: true,                      // auto-open browser
+      https: false,                    // enable HTTPS
+      historyApiFallback: true,        // SPA routing fallback
+    },
+    transport: {
+      baseUrl: "",                     // API base URL (for separate API host)
+      endpoint: "/api/fn",             // server function endpoint path
+    },
+  },
+  server: {
+    endpoint: "/api/fn",               // must match client transport endpoint
+    runner: "@evjs/runtime/server/node",
+    middleware: [
+      "./src/middleware/auth.ts",      // middleware module paths
+      "./src/middleware/logging.ts",
+    ],
+    dev: {
+      port: 3001,                      // API server port in dev mode
+    },
+  },
+});
+```
+
+### Config Defaults
+
+| Key | Default |
+|-----|---------|
+| `client.entry` | `"./src/main.tsx"` |
+| `client.html` | `"./index.html"` |
+| `client.dev.port` | `3000` |
+| `server.endpoint` | `"/api/fn"` |
+| `server.dev.port` | `3001` |
+| `server.runner` | `"@evjs/runtime/server/node"` |
+
+## Project Structure
+
+```
+my-app/
+├── ev.config.ts          # optional config
+├── index.html            # HTML template
+├── package.json
+├── tsconfig.json
+└── src/
+    ├── main.tsx           # app bootstrap (keep minimal)
+    ├── routes.tsx         # route tree + components
+    ├── api/               # server functions
+    │   ├── users.server.ts
+    │   └── posts.server.ts
+    └── middleware/         # server middleware (optional)
+        └── auth.ts
+```
+
+## CLI Commands
+
+### `ev init [project-name]`
+Interactive scaffolding. Templates:
+- `basic-csr` — client-side rendering only
+- `basic-server-fns` — server functions example
+- `configured-server-fns` — advanced config example
+- `complex-routing` — params, search, layouts, loaders
+
+### `ev dev`
+- Starts webpack-dev-server on port 3000
+- Auto-starts API server on port 3001
+- Proxies `/api/fn` requests to API server
+- Hot reloads client; restarts server on changes
+- `NODE_ENV=development`
+
+### `ev build`
+- Outputs client bundle to `dist/client/`
+- Outputs server bundle to `dist/server/`
+- Emits `dist/server/manifest.json` with server function registry
+- `NODE_ENV=production`
+
+## Common Mistakes
+
+1. **Don't create `webpack.config.cjs`** — use `ev.config.ts` instead
+2. **Don't install webpack manually** — it's a dependency of `@evjs/cli`
+3. **Config file must be `ev.config.ts`** — not `evjs.config.ts` or `evjs.config.ts`
+4. **Import `defineConfig` from `@evjs/cli`** — not from `@evjs/runtime`
+
+## Dependencies (bundled)
+
+Users do NOT need to install these — they're included in `@evjs/cli`:
+- `webpack`, `webpack-dev-server`, `webpack-cli`
+- `html-webpack-plugin`, `swc-loader`, `@swc/core`
+- `@evjs/webpack-plugin`

package/README.md

@@ -0,0 +1,67 @@
+# @evjs/cli
+
+> CLI and configuration for the **@evjs/cli** meta-framework.
+
+## Install
+
+```bash
+npm install -g @evjs/cli
+```
+
+## Zero-Config
+
+No configuration file is needed. `ev dev` and `ev build` work out of the box with sensible defaults:
+
+- Entry: `./src/main.tsx`
+- HTML: `./index.html`
+- Client dev server: port 3000
+- API server (dev): port 3001
+- Server functions auto-discovered via `"use server"` directive
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ev init [name]` | Scaffold a new project from a template |
+| `ev dev` | Start dev server (client HMR + API watch) |
+| `ev build` | Production build (client + server) |
+
+### `ev init [name]`
+
+Templates: `basic-csr`, `basic-server-fns`, `trpc-server-fns`.
+Option: `-t, --template <template>` to skip interactive selection.
+
+### `ev dev`
+
+Uses webpack Node API directly (no temp config files):
+1. **WebpackDevServer** (port 3000) — client bundle with HMR.
+2. **Node API Server** (port 3001) — auto-starts when server bundle is emitted, uses `node --watch`.
+
+### `ev build`
+
+Runs webpack via Node API with `NODE_ENV=production`:
+- `dist/client/` — optimized client assets with content hashes.
+- `dist/server/main.[hash].js` — server bundle (entry discovered via `dist/server/manifest.json`).
+
+## Configuration
+
+Create `ev.config.ts` in the project root (optional):
+
+```ts
+import { defineConfig } from "@evjs/cli";
+
+export default defineConfig({
+  client: {
+    entry: "./src/main.tsx",
+    html: "./index.html",
+    dev: { port: 3000 },
+  },
+  server: {
+    endpoint: "/api/fn",
+    middleware: [],
+    dev: { port: 3001 },
+  },
+});
+```
+
+The `client.dev` and `server.dev` fields accept extra options that are merged with defaults.

package/dist/config.js

@@ -0,0 +1,35 @@
+/**
+ * Default configuration values.
+ *
+ * Single source of truth for all defaults across the framework.
+ */
+export const CONFIG_DEFAULTS = {
+    entry: "./src/main.tsx",
+    html: "./index.html",
+    clientPort: 3000,
+    serverPort: 3001,
+    endpoint: "/api/fn",
+};
+/**
+ * Define configuration for the evjs framework.
+ *
+ * @example
+ * ```ts
+ * // ev.config.ts
+ * import { defineConfig } from "@evjs/cli";
+ *
+ * export default defineConfig({
+ *   client: {
+ *     entry: "./src/main.tsx",
+ *     dev: { port: 3000 },
+ *   },
+ *   server: {
+ *     endpoint: "/api/fn",
+ *     dev: { port: 3001 },
+ *   },
+ * });
+ * ```
+ */
+export function defineConfig(config) {
+    return config;
+}

package/dist/create-webpack-config.js

@@ -0,0 +1,99 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { CONFIG_DEFAULTS } from "./config.js";
+const esmRequire = createRequire(import.meta.url);
+/**
+ * Create a webpack configuration object from EvfConfig.
+ *
+ * Returns a plain object that can be passed directly to the webpack Node API.
+ * No temp files are generated.
+ */
+export function createWebpackConfig(config, cwd) {
+    const client = config?.client;
+    const server = config?.server;
+    const entry = client?.entry ?? CONFIG_DEFAULTS.entry;
+    const html = client?.html ?? CONFIG_DEFAULTS.html;
+    const clientPort = client?.dev?.port ?? CONFIG_DEFAULTS.clientPort;
+    const serverPort = server?.dev?.port ?? CONFIG_DEFAULTS.serverPort;
+    const endpoint = server?.endpoint ?? CONFIG_DEFAULTS.endpoint;
+    const isProduction = process.env.NODE_ENV === "production";
+    const HtmlWebpackPlugin = esmRequire("html-webpack-plugin");
+    const { EvWebpackPlugin } = esmRequire("@evjs/webpack-plugin");
+    const pluginOptions = server?.middleware?.length
+        ? { server: { middleware: server.middleware } }
+        : undefined;
+    // Resolve loader paths from evjs's dependency tree so they work
+    // even when the user's project doesn't list them as direct deps.
+    const resolveLoader = (id) => {
+        try {
+            return esmRequire.resolve(id);
+        }
+        catch {
+            return id;
+        }
+    };
+    // Derive the proxy base path from the configured endpoint.
+    // e.g. "/api/fn" → "/api", "/rpc/v1" → "/rpc"
+    const proxyBase = `/${endpoint.split("/").filter(Boolean)[0] || "api"}`;
+    // Destructure port out of dev overrides to avoid passing it twice.
+    const { port: _p, ...devServerOverrides } = client?.dev ?? {};
+    return {
+        name: "client",
+        mode: isProduction ? "production" : "development",
+        devtool: isProduction ? "hidden-source-map" : "source-map",
+        entry,
+        output: {
+            path: path.resolve(cwd, "dist/client"),
+            filename: isProduction ? "[name].[contenthash:8].js" : "index.js",
+            clean: true,
+        },
+        resolve: {
+            extensions: [".tsx", ".ts", ".js"],
+        },
+        module: {
+            rules: [
+                {
+                    test: /\.m?js/,
+                    resolve: { fullySpecified: false },
+                },
+                {
+                    test: /\.tsx?$/,
+                    exclude: /node_modules/,
+                    use: [
+                        {
+                            loader: resolveLoader("swc-loader"),
+                            options: {
+                                jsc: {
+                                    parser: { syntax: "typescript", tsx: true },
+                                    transform: { react: { runtime: "automatic" } },
+                                },
+                            },
+                        },
+                        {
+                            loader: resolveLoader("@evjs/webpack-plugin/server-fn-loader"),
+                        },
+                    ],
+                },
+            ],
+        },
+        plugins: [
+            new HtmlWebpackPlugin({ template: html }),
+            new EvWebpackPlugin(pluginOptions),
+        ],
+        optimization: isProduction
+            ? { splitChunks: { chunks: "all" } }
+            : undefined,
+        devServer: {
+            port: clientPort,
+            hot: true,
+            devMiddleware: { writeToDisk: true },
+            proxy: [
+                {
+                    context: [proxyBase],
+                    target: `http://localhost:${serverPort}`,
+                },
+            ],
+            ...devServerOverrides,
+        },
+    };
+}

package/dist/index.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { configure, getConsoleSink, getLogger } from "@logtape/logtape";
+import { Command } from "commander";
+import { execa } from "execa";
+import fs from "fs-extra";
+import prompts from "prompts";
+import { CONFIG_DEFAULTS } from "./config.js";
+const esmRequire = createRequire(import.meta.url);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+await configure({
+    sinks: { console: getConsoleSink() },
+    loggers: [
+        { category: ["logtape", "meta"], lowestLevel: "warning" },
+        { category: ["evjs"], sinks: ["console"], lowestLevel: "info" },
+    ],
+});
+const logger = getLogger(["evjs", "cli"]);
+const pkg = fs.readJsonSync(path.resolve(__dirname, "../package.json"));
+const program = new Command();
+program
+    .name("ev")
+    .description("CLI for the evjs framework")
+    .version(pkg.version);
+program
+    .command("init")
+    .description("Initialize a new evjs project")
+    .argument("[name]", "Project name")
+    .option("-t, --template <template>", "Template to use")
+    .action(async (name, options) => {
+    const response = await prompts([
+        {
+            type: name ? null : "text",
+            name: "projectName",
+            message: "Project name:",
+            initial: name || "my-evjs-app",
+        },
+        {
+            type: options.template ? null : "select",
+            name: "template",
+            message: "Select a template:",
+            choices: [
+                { title: "Basic CSR (Client-Side Rendering)", value: "basic-csr" },
+                { title: "Basic Server Functions", value: "basic-server-fns" },
+                {
+                    title: "Configured Server Functions (ev.config.ts + Query)",
+                    value: "configured-server-fns",
+                },
+                {
+                    title: "Complex Routing (params, search, layouts, loaders)",
+                    value: "complex-routing",
+                },
+            ],
+        },
+    ], {
+        onCancel: () => {
+            process.exit(1);
+        },
+    });
+    const projectName = response.projectName || name;
+    const template = response.template || options.template;
+    const targetDir = path.resolve(process.cwd(), projectName);
+    if (fs.existsSync(targetDir)) {
+        logger.error `Directory ${projectName} already exists!`;
+        process.exit(1);
+    }
+    const templateDir = path.resolve(__dirname, "../templates", template);
+    if (!fs.existsSync(templateDir)) {
+        logger.error `Template ${template} not found!`;
+        process.exit(1);
+    }
+    logger.info `Scaffolding project in ${targetDir}...`;
+    await fs.copy(templateDir, targetDir, {
+        dereference: true,
+        filter: (src) => {
+            const basename = path.basename(src);
+            return !["node_modules", "dist", ".turbo"].includes(basename);
+        },
+    });
+    // Post-process package.json: sync @evjs/* versions and set project name
+    const pkgPath = path.join(targetDir, "package.json");
+    if (fs.existsSync(pkgPath)) {
+        const pkg = await fs.readJson(pkgPath);
+        pkg.name = projectName;
+        delete pkg.private; // Templates shouldn't be private by default
+        const updateDeps = (deps) => {
+            if (!deps)
+                return;
+            for (const [name, val] of Object.entries(deps)) {
+                // Sync all @evjs/* packages to current CLI version
+                if (name.startsWith("@evjs/") &&
+                    (val === "*" ||
+                        (typeof val === "string" && val.includes("workspace")))) {
+                    deps[name] = `^${pkg.version}`;
+                }
+            }
+        };
+        updateDeps(pkg.dependencies);
+        updateDeps(pkg.devDependencies);
+        await fs.writeJson(pkgPath, pkg, { spaces: 2 });
+    }
+    logger.info `Done! Now run:`;
+    logger.info `  cd ${projectName}`;
+    logger.info `  npm install`;
+    logger.info `  npm run dev`;
+});
+/**
+ * Load config and create webpack configuration object.
+ *
+ * Uses ev.config.ts when present, otherwise falls back to zero-config defaults.
+ * No webpack.config.cjs fallback — the meta-framework owns the build config.
+ */
+async function resolveWebpackConfig(cwd) {
+    const { loadConfig } = await import("./load-config.js");
+    const evjsConfig = await loadConfig(cwd);
+    const { createWebpackConfig } = await import("./create-webpack-config.js");
+    logger.info `Using ${evjsConfig ? "ev.config.ts" : "zero-config defaults"}`;
+    const webpackConfig = createWebpackConfig(evjsConfig, cwd);
+    return { evjsConfig, webpackConfig };
+}
+program
+    .command("dev")
+    .description("Start development server")
+    .action(async () => {
+    const cwd = process.cwd();
+    process.env.NODE_ENV ??= "development";
+    const { evjsConfig, webpackConfig } = await resolveWebpackConfig(cwd);
+    const serverPort = evjsConfig?.server?.dev?.port ?? CONFIG_DEFAULTS.serverPort;
+    logger.info `Starting development server...`;
+    try {
+        const webpack = esmRequire("webpack");
+        const WebpackDevServer = esmRequire("webpack-dev-server");
+        const compiler = webpack(webpackConfig);
+        const devServerOptions = webpackConfig.devServer ?? {};
+        const server = new WebpackDevServer(devServerOptions, compiler);
+        await server.start();
+        // Background: wait for server bundle, then start Node API
+        void (async () => {
+            const manifestPath = path.resolve(cwd, "dist/server/manifest.json");
+            const bootstrapPath = path.resolve(cwd, "dist/server/_dev_start.cjs");
+            let started = false;
+            while (true) {
+                if (fs.existsSync(manifestPath)) {
+                    if (!started) {
+                        const runnerConfig = evjsConfig?.server?.runner ?? "node";
+                        const [runner, ...runnerExtraArgs] = runnerConfig.split(/\s+/);
+                        logger.info `Server bundle detected, starting ${runner} API...`;
+                        started = true;
+                        const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+                        const serverBundlePath = path.resolve(cwd, "dist/server", manifest.entry);
+                        fs.writeFileSync(bootstrapPath, [
+                            `const bundle = require(${JSON.stringify(serverBundlePath)});`,
+                            `const app = bundle.createApp({ endpoint: ${JSON.stringify(evjsConfig?.server?.endpoint ?? CONFIG_DEFAULTS.endpoint)} });`,
+                            `const { serve } = require("@evjs/runtime/server/node");`,
+                            `serve(app, { port: ${serverPort} });`,
+                        ].join("\n"));
+                        // node gets --watch flags; other runtimes use their own args as-is
+                        const runnerArgs = runner === "node"
+                            ? [
+                                "--watch",
+                                "--watch-preserve-output",
+                                ...runnerExtraArgs,
+                                bootstrapPath,
+                            ]
+                            : [...runnerExtraArgs, bootstrapPath];
+                        try {
+                            await execa(runner, runnerArgs, {
+                                stdio: "inherit",
+                                env: { ...process.env, NODE_ENV: "development" },
+                            });
+                        }
+                        catch (_e) {
+                            started = false;
+                        }
+                    }
+                }
+                await new Promise((r) => setTimeout(r, 500));
+            }
+        })().catch((err) => {
+            logger.error `Server runner failed: ${err}`;
+            process.exit(1);
+        });
+    }
+    catch (err) {
+        logger.error `Dev server failed to start: ${err}`;
+        process.exit(1);
+    }
+});
+program
+    .command("build")
+    .description("Build project for production")
+    .action(async () => {
+    const cwd = process.cwd();
+    process.env.NODE_ENV ??= "production";
+    const { webpackConfig } = await resolveWebpackConfig(cwd);
+    logger.info `Building for production...`;
+    const webpack = esmRequire("webpack");
+    const compiler = webpack(webpackConfig);
+    await new Promise((resolve, reject) => {
+        compiler.run((err, stats) => {
+            if (err) {
+                reject(err);
+                return;
+            }
+            console.log(stats.toString({
+                colors: true,
+                modules: false,
+                children: true,
+            }));
+            if (stats.hasErrors()) {
+                process.exit(1);
+            }
+            compiler.close(() => resolve());
+        });
+    });
+    logger.info `Build complete!`;
+});
+program.parse();

package/dist/load-config.js

@@ -0,0 +1,39 @@
+import fs from "node:fs";
+import path from "node:path";
+const CONFIG_FILES = ["ev.config.ts", "ev.config.js", "ev.config.mjs"];
+/**
+ * Ensure a TypeScript loader is registered before importing `.ts` config files.
+ * Tries `@swc-node/register/esm-register` (ships alongside `@swc/core` which
+ * the CLI already bundles), then falls back to Node's built-in `--loader tsx`
+ * pathway. If neither is available the raw `import()` is attempted anyway —
+ * Node will throw a clear error telling the user to install a loader.
+ */
+async function ensureTsLoader() {
+    try {
+        // @ts-expect-error — optional dependency, may not be installed
+        await import("@swc-node/register/esm-register");
+    }
+    catch {
+        // Loader not available — Node may still handle .ts via --loader flag
+    }
+}
+/**
+ * Load evjs config from the project root.
+ *
+ * Looks for `ev.config.ts`, `.js`, or `.mjs` in the given directory.
+ * Returns undefined if no config file is found.
+ */
+export async function loadConfig(cwd) {
+    for (const filename of CONFIG_FILES) {
+        const configPath = path.resolve(cwd, filename);
+        if (fs.existsSync(configPath)) {
+            // Register TS loader for .ts config files
+            if (filename.endsWith(".ts")) {
+                await ensureTsLoader();
+            }
+            const mod = await import(configPath);
+            return mod.default ?? mod;
+        }
+    }
+    return undefined;
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@evjs/cli",
+  "version": "0.0.1-rc.13",
+  "description": "CLI and configuration layer for the evjs framework",
+  "type": "module",
+  "main": "./dist/config.js",
+  "types": "./dist/config.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "ev": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "AGENT.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w",
+    "test": "vitest run",
+    "check-types": "tsc --noEmit",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "@evjs/webpack-plugin": "0.0.1-rc.13",
+    "@logtape/logtape": "^2.0.4",
+    "@swc/core": "^1.2.147",
+    "commander": "^12.1.0",
+    "execa": "^9.5.2",
+    "fs-extra": "^11.3.0",
+    "glob": "^13.0.6",
+    "html-webpack-plugin": "^5.6.6",
+    "picocolors": "^1.1.1",
+    "prompts": "^2.4.2",
+    "swc-loader": "^0.2.7",
+    "webpack": "^5.105.4",
+    "webpack-cli": "^6.0.1",
+    "webpack-dev-server": "^5.2.3"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^22.13.5",
+    "@types/prompts": "^2.4.9",
+    "typescript": "^5.7.3"
+  },
+  "homepage": "https://github.com/evaijs/evjs#readme",
+  "bugs": {
+    "url": "https://github.com/evaijs/evjs/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/evaijs/evjs.git"
+  },
+  "keywords": [
+    "evjs",
+    "cli",
+    "react",
+    "server-functions",
+    "scaffolding",
+    "dev-server",
+    "typescript",
+    "full-stack",
+    "framework"
+  ],
+  "license": "MIT",
+  "author": "xusd320"
+}

package/templates/basic-csr/index.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>ev — Basic CSR Example</title>
+  </head>
+  <body>
+    <div id="app"></div>
+  </body>
+</html>

package/templates/basic-csr/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "example-basic-csr",
+  "version": "0.0.1-rc.8",
+  "private": true,
+  "scripts": {
+    "dev": "ev dev",
+    "build": "ev build",
+    "check-types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@evjs/runtime": "^0.0.1-rc.13",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4"
+  },
+  "devDependencies": {
+    "@evjs/cli": "^0.0.1-rc.5",
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
+    "typescript": "^5.7.3"
+  }
+}