@evjs/cli 0.0.2 → 0.0.4

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { configure, getConsoleSink } from "@logtape/logtape";
+import { Command } from "commander";
+import fs from "fs-extra";
+import { build, dev } from "./index.js";
+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 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("dev")
+    .description("Start development server")
+    .action(async () => {
+    const cwd = process.cwd();
+    const { loadConfig } = await import("./load-config.js");
+    const config = await loadConfig(cwd);
+    try {
+        await dev(config ?? undefined, { cwd });
+    }
+    catch (err) {
+        console.error(err);
+        process.exit(1);
+    }
+});
+program
+    .command("build")
+    .description("Build project for production")
+    .action(async () => {
+    const cwd = process.cwd();
+    const { loadConfig } = await import("./load-config.js");
+    const config = await loadConfig(cwd);
+    try {
+        await build(config ?? undefined, { cwd });
+    }
+    catch (err) {
+        console.error(err);
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/config.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Server configuration.
+ *
+ * Controls server backend, entry, plugins, and dev options.
+ */
+export interface ServerConfig {
+    /** Explicit server entry file. If provided, overrides auto-generated entry. */
+    entry?: string;
+    /** Server backend command. Default: "node". */
+    backend?: string;
+    /** Server function configuration. */
+    functions?: {
+        /** Server function endpoint path. Default: "/api/fn". */
+        endpoint?: string;
+    };
+    /** Build plugins for the server bundle. */
+    plugins?: EvPlugin[];
+    /** Dev server options. */
+    dev?: {
+        /** API server port (dev mode). Default: 3001. */
+        port?: number;
+        /** Enable HTTPS. */
+        https?: boolean;
+    };
+}
+/**
+ * Client configuration.
+ *
+ * Controls entry point, HTML template, dev server, and transport.
+ */
+export interface ClientConfig {
+    /** Client entry point. Default: "./src/main.tsx". */
+    entry?: string;
+    /** HTML template path. Default: "./index.html". */
+    html?: string;
+    /** Build plugins for the client bundle. */
+    plugins?: EvPlugin[];
+    /** Dev server options. */
+    dev?: {
+        /** Dev server port. Default: 3000. */
+        port?: number;
+        /** Enable HTTPS. */
+        https?: boolean;
+    };
+}
+/**
+ * A single loader entry.
+ *
+ * Can be a plain package name or an object with per-loader options.
+ *
+ * @example
+ * ```ts
+ * "css-loader"
+ * { loader: "css-loader", options: { modules: true } }
+ * ```
+ */
+export type EvLoaderEntry = string | {
+    loader: string;
+    options?: Record<string, unknown>;
+};
+/** A loader rule declared by a plugin. */
+export interface EvPluginLoader {
+    /** File matching pattern (e.g. /\.css$/, /\.svg$/). */
+    test: RegExp;
+    /** Pattern to exclude (e.g. /node_modules/). */
+    exclude?: RegExp;
+    /** Loader(s) to apply. */
+    use: EvLoaderEntry | EvLoaderEntry[];
+}
+/** An evjs build plugin. */
+export interface EvPlugin {
+    /** Plugin name for debugging and logging. */
+    name: string;
+    /** Loaders to add to the build pipeline. */
+    loaders?: EvPluginLoader[];
+}
+/**
+ * evjs framework configuration.
+ */
+export interface EvConfig {
+    server?: ServerConfig;
+    client?: ClientConfig;
+}
+/**
+ * Default configuration values.
+ *
+ * Single source of truth for all defaults across the framework.
+ */
+export declare const CONFIG_DEFAULTS: {
+    readonly entry: "./src/main.tsx";
+    readonly html: "./index.html";
+    readonly clientPort: 3000;
+    readonly serverPort: 3001;
+    readonly 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: {
+ *     functions: { endpoint: "/api/fn" },
+ *     dev: { port: 3001 },
+ *   },
+ * });
+ * ```
+ */
+export declare function defineConfig(config: EvConfig): EvConfig;

package/dist/config.js

@@ -24,7 +24,7 @@ export const CONFIG_DEFAULTS = {
  *     dev: { port: 3000 },
  *   },
  *   server: {
- *     endpoint: "/api/fn",
+ *     functions: { endpoint: "/api/fn" },
  *     dev: { port: 3001 },
  *   },
  * });

package/dist/create-webpack-config.d.ts

@@ -0,0 +1,8 @@
+import { type EvConfig } from "./config.js";
+/**
+ * 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 declare function createWebpackConfig(config: EvConfig | undefined, cwd: string): Record<string, unknown>;

package/dist/create-webpack-config.js

@@ -15,7 +15,7 @@ export function createWebpackConfig(config, cwd) {
     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 endpoint = server?.functions?.endpoint ?? CONFIG_DEFAULTS.endpoint;
     const isProduction = process.env.NODE_ENV === "production";
     const HtmlWebpackPlugin = esmRequire("html-webpack-plugin");
     const { EvWebpackPlugin } = esmRequire("@evjs/webpack-plugin");
@@ -74,8 +74,8 @@ export function createWebpackConfig(config, cwd) {
                         },
                     ],
                 },
-                // Plugin-declared loaders
-                ...(client?.plugins ?? []).flatMap((plugin) => (plugin.loaders ?? []).map((rule) => {
+                // Plugin-declared loaders (client + server)
+                ...[...(client?.plugins ?? []), ...(server?.plugins ?? [])].flatMap((plugin) => (plugin.loaders ?? []).map((rule) => {
                     const entries = Array.isArray(rule.use) ? rule.use : [rule.use];
                     return {
                         test: rule.test,

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import type { EvConfig } from "./config.js";
+export type { ClientConfig, EvConfig, EvLoaderEntry, EvPlugin, EvPluginLoader, ServerConfig, } from "./config.js";
+export { CONFIG_DEFAULTS, defineConfig } from "./config.js";
+export interface DevOptions {
+    cwd?: string;
+}
+/**
+ * Start the development server programmatically.
+ *
+ * @param config - evjs configuration object (from `defineConfig`)
+ * @param options - additional options like `cwd`
+ */
+export declare function dev(config?: EvConfig, options?: DevOptions): Promise<void>;
+export interface BuildOptions {
+    cwd?: string;
+}
+/**
+ * Run a production build programmatically.
+ *
+ * @param config - evjs configuration object (from `defineConfig`)
+ * @param options - additional options like `cwd`
+ */
+export declare function build(config?: EvConfig, options?: BuildOptions): Promise<void>;

package/dist/index.js

@@ -1,119 +1,96 @@
-#!/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 { getLogger } from "@logtape/logtape";
 import { execa } from "execa";
 import fs from "fs-extra";
 import { CONFIG_DEFAULTS } from "./config.js";
+export { CONFIG_DEFAULTS, defineConfig } 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);
 /**
- * Load config and create webpack configuration object.
- *
- * Uses ev.config.ts when present, otherwise falls back to convention-based defaults.
- * No webpack.config.cjs fallback — the meta-framework owns the build config.
+ * Create webpack configuration from an EvConfig object.
  */
-async function resolveWebpackConfig(cwd) {
-    const { loadConfig } = await import("./load-config.js");
-    const evjsConfig = await loadConfig(cwd);
+async function resolveWebpackConfig(config, cwd) {
     const { createWebpackConfig } = await import("./create-webpack-config.js");
-    logger.info `Using ${evjsConfig ? "ev.config.ts" : "convention-based defaults"}`;
-    const webpackConfig = createWebpackConfig(evjsConfig, cwd);
-    return { evjsConfig, webpackConfig };
+    return createWebpackConfig(config, cwd);
 }
-program
-    .command("dev")
-    .description("Start development server")
-    .action(async () => {
-    const cwd = process.cwd();
+/**
+ * Start the development server programmatically.
+ *
+ * @param config - evjs configuration object (from `defineConfig`)
+ * @param options - additional options like `cwd`
+ */
+export async function dev(config, options) {
+    const cwd = options?.cwd ?? process.cwd();
     process.env.NODE_ENV ??= "development";
-    const { evjsConfig, webpackConfig } = await resolveWebpackConfig(cwd);
-    const serverPort = evjsConfig?.server?.dev?.port ?? CONFIG_DEFAULTS.serverPort;
+    const webpackConfig = await resolveWebpackConfig(config, cwd);
+    const serverPort = config?.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: start Node API when server bundle is ready
-        let apiStarted = false;
-        compiler.hooks.done.tap("EvDevServer", async () => {
-            if (apiStarted)
+    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: start Node API when server bundle is ready
+    let apiStarted = false;
+    compiler.hooks.done.tap("EvDevServer", async () => {
+        if (apiStarted)
+            return;
+        const manifestPath = path.resolve(cwd, "dist/manifest.json");
+        const bootstrapPath = path.resolve(cwd, "dist/server/_dev_start.cjs");
+        if (fs.existsSync(manifestPath)) {
+            const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+            // Start API server if there's a server entry
+            if (!manifest.server?.entry)
                 return;
-            const manifestPath = path.resolve(cwd, "dist/manifest.json");
-            const bootstrapPath = path.resolve(cwd, "dist/server/_dev_start.cjs");
-            if (fs.existsSync(manifestPath)) {
-                const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
-                // Start API server if there's a server entry
-                if (!manifest.server?.entry)
-                    return;
-                apiStarted = true;
-                const backendConfig = evjsConfig?.server?.backend ?? "node";
-                const [backend, ...backendExtraArgs] = backendConfig.split(/\s+/);
-                logger.info `Server bundle detected, starting ${backend} API...`;
-                try {
-                    const serverBundlePath = path.resolve(cwd, "dist/server", manifest.server.entry);
-                    fs.ensureDirSync(path.dirname(bootstrapPath));
-                    fs.writeFileSync(bootstrapPath, [
-                        `const bundle = require(${JSON.stringify(serverBundlePath)});`,
-                        `const app = bundle.app || bundle.createApp({ endpoint: ${JSON.stringify(evjsConfig?.server?.endpoint ?? CONFIG_DEFAULTS.endpoint)} });`,
-                        `const { serve } = require("@evjs/server/node");`,
-                        `serve(app, { port: ${serverPort} });`,
-                    ].join("\n"));
-                    // node gets --watch flags; other runtimes use their own args as-is
-                    const backendArgs = backend === "node"
-                        ? [
-                            "--watch",
-                            "--watch-preserve-output",
-                            ...backendExtraArgs,
-                            bootstrapPath,
-                        ]
-                        : [...backendExtraArgs, bootstrapPath];
-                    // Don't await execa here since it's a long-running watch process
-                    execa(backend, backendArgs, {
-                        stdio: "inherit",
-                        env: { ...process.env, NODE_ENV: "development" },
-                    }).catch(() => {
-                        apiStarted = false;
-                    });
-                }
-                catch (err) {
-                    logger.error `Server backend failed: ${err}`;
+            apiStarted = true;
+            const backendConfig = config?.server?.backend ?? "node";
+            const [backend, ...backendExtraArgs] = backendConfig.split(/\s+/);
+            logger.info `Server bundle detected, starting ${backend} API...`;
+            try {
+                const serverBundlePath = path.resolve(cwd, "dist/server", manifest.server.entry);
+                fs.ensureDirSync(path.dirname(bootstrapPath));
+                fs.writeFileSync(bootstrapPath, [
+                    `const bundle = require(${JSON.stringify(serverBundlePath)});`,
+                    `const app = bundle.app || bundle.createApp({ endpoint: ${JSON.stringify(config?.server?.functions?.endpoint ?? CONFIG_DEFAULTS.endpoint)} });`,
+                    `const { serve } = require("@evjs/server/node");`,
+                    `serve(app, { port: ${serverPort}, https: ${Boolean(config?.server?.dev?.https)} });`,
+                ].join("\n"));
+                // node gets --watch flags; other runtimes use their own args as-is
+                const backendArgs = backend === "node"
+                    ? [
+                        "--watch",
+                        "--watch-preserve-output",
+                        ...backendExtraArgs,
+                        bootstrapPath,
+                    ]
+                    : [...backendExtraArgs, bootstrapPath];
+                // Don't await execa here since it's a long-running watch process
+                execa(backend, backendArgs, {
+                    stdio: "inherit",
+                    env: { ...process.env, NODE_ENV: "development" },
+                }).catch(() => {
                     apiStarted = false;
-                }
+                });
             }
-        });
-    }
-    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();
+            catch (err) {
+                logger.error `Server backend failed: ${err}`;
+                apiStarted = false;
+            }
+        }
+    });
+}
+/**
+ * Run a production build programmatically.
+ *
+ * @param config - evjs configuration object (from `defineConfig`)
+ * @param options - additional options like `cwd`
+ */
+export async function build(config, options) {
+    const cwd = options?.cwd ?? process.cwd();
     process.env.NODE_ENV ??= "production";
-    const { webpackConfig } = await resolveWebpackConfig(cwd);
+    const webpackConfig = await resolveWebpackConfig(config, cwd);
     logger.info `Building for production...`;
     const webpack = esmRequire("webpack");
     const compiler = webpack(webpackConfig);
@@ -135,5 +112,4 @@ program
         });
     });
     logger.info `Build complete!`;
-});
-program.parse();
+}

package/dist/load-config.d.ts

@@ -0,0 +1,8 @@
+import type { EvConfig } from "./config.js";
+/**
+ * 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 declare function loadConfig(cwd: string): Promise<EvConfig | undefined>;

package/package.json

@@ -1,21 +1,21 @@
 {
   "name": "@evjs/cli",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "CLI and configuration layer for the evjs framework",
   "type": "module",
-  "main": "./dist/config.js",
-  "types": "./dist/config.d.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/config.d.ts",
-      "import": "./dist/config.js"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "bin": {
-    "ev": "dist/index.js"
+    "ev": "dist/cli.js"
   },
   "files": [
     "dist"