ee-bin 5.0.0-beta.2 → 5.0.0-beta.5

package/dist/esm/tools/serve.d.ts

@@ -1,15 +1,27 @@
-import crossSpawn from 'cross-spawn';
-interface ExecConfig {
-    directory: string;
-    cmd: string;
-    args?: string[] | string;
-    stdio?: string;
-    sync?: boolean;
-    protocol?: string;
-    watch?: boolean;
-    delay?: number;
-    [key: string]: unknown;
-}
+/**
+ * Dev/Build/Start Manager — ee-bin's core dispatcher
+ *
+ * The ServeProcess class manages the full dev/build/start/exec lifecycle and is the
+ * most complex module in ee-bin. Core responsibilities:
+ *   1. dev  — Start frontend dev server + Electron process, optional watch mode with auto-rebuild
+ *   2. build — Bundle Electron code + execute electron-builder platform build commands
+ *   3. start — Start Electron in production mode
+ *   4. exec  — Execute user-defined custom commands
+ *
+ * Process management strategy:
+ *   - execProcess only tracks async ChildProcess instances (sync executions are already
+ *     complete, so there's no process to manage)
+ *   - SIGINT/SIGTERM signal handlers close all child processes and restore package.json main field
+ *   - In watch mode, debounce + tree-kill terminate the old Electron process before restarting
+ *
+ * Bundling strategy:
+ *   - bundle mode: esbuild bundles into a single file + virtual registry plugin
+ *   - copy mode: directly copies the entire electron/ directory (for non-bundling scenarios)
+ *   - After bundling, switches package.json main field to point to ./public/electron/main.js
+ */
+import { ChildProcess } from 'child_process';
+import type { ExecConfig, BundleConfig } from '../types/config.js';
+/** Common options for ServeProcess methods — corresponds to Commander CLI parameters */
 interface ServeOptions {
     config?: string;
     serve?: string;
@@ -17,25 +29,150 @@ interface ServeOptions {
     env?: string;
 }
 declare class ServeProcess {
-    execProcess: Record<string, ReturnType<typeof crossSpawn>>;
-    electronDir: string;
-    bundleDir: string;
-    pkgPath: string;
+    /** Async child process reference table (only async ChildProcess instances; sync processes are already complete and don't need tracking) */
+    execProcess: Record<string, ChildProcess>;
+    /** Original value of package.json main field (used by _restorePkgMain to restore) */
+    private originalPkgMain;
     constructor();
-    _init(): void;
-    _closeProcess(): Promise<void>;
-    dev(options?: ServeOptions): void;
-    start(options?: ServeOptions): void;
-    sleep(ms: number): Promise<void>;
-    build(options?: ServeOptions): void;
+    /** Register SIGINT/SIGTERM signal handlers to ensure child processes are closed and config is restored on exit */
+    private _init;
+    /**
+     * Close all child processes, restore package.json, then exit
+     *
+     * Flow: kill all child processes → restore pkgMain → sleep 500ms → process.exit(0)
+     * NOTE: The 500ms sleep is a compromise. The ideal approach would be to listen for each
+     * child process's exit event before exiting, but that's complex to implement (multi-process
+     * racing, nested processes, etc.). If a child process doesn't close in time, it may be orphaned.
+     */
+    private _closeProcess;
+    /**
+     * Dev mode — start frontend dev server + Electron process
+     *
+     * Complete flow:
+     *   1. Set NODE_ENV=dev
+     *   2. Load config, parse command names to start
+     *   3. If electron command is included:
+     *      a. First bundle Electron code (via esbuild)
+     *      b. Switch package.json main field
+     *      c. If electron.watch=true, watch electron/ directory for changes
+     *         → on change: debounce → re-bundle → kill old process → re-spawn
+     *   4. multiExec starts all commands (frontend + Electron)
+     */
+    dev(options?: ServeOptions): Promise<void>;
+    /**
+     * Production start — directly run the Electron process (no bundling)
+     * Prerequisite: the project has already been built via the build command
+     */
+    start(options?: ServeOptions): Promise<void>;
+    /** Helper: sleep for the specified number of milliseconds */
+    private sleep;
+    /**
+     * Build mode — bundle Electron code + execute platform build commands
+     *
+     * Complete flow:
+     *   1. Set NODE_ENV=prod (or user-specified environment)
+     *   2. If cmds includes 'electron': bundle first → remove electron from command list → switch pkgMain
+     *   3. multiExec executes remaining commands (e.g. frontend, win64, mac, etc.)
+     *   4. After build completes, restore package.json main field
+     *
+     * The 'electron' command only triggers bundling, not an Electron process launch,
+     * so it's removed from the command list and not processed by multiExec
+     */
+    build(options?: ServeOptions): Promise<void>;
+    /** Execute user-defined custom commands from the "exec" config section */
     exec(options?: ServeOptions): void;
+    /**
+     * Execute multiple commands — iterate the command list and start a subprocess for each
+     *
+     * Design decisions:
+     *   - Frontend file:// protocol is skipped in dev mode (frontend is already served via HTTP)
+     *   - sync mode uses crossSpawnSync for blocking execution; result is not stored in execProcess (process already complete)
+     *   - async mode uses crossSpawn for non-blocking execution; stored in execProcess for later kill
+     *   - async processes listen for exit events; in dev mode, a message is logged when a process exits
+     */
     multiExec(opt: {
         binCmd: string;
-        binCmdConfig: Record<string, ExecConfig>;
+        binCmdConfig: Record<string, ExecConfig | undefined>;
         command: string;
     }): void;
-    bundle(bundleConfig?: Record<string, unknown>): void;
-    _switchPkgMain(isDebugger?: boolean): void;
+    /**
+     * Bundle Electron main process code
+     *
+     * Two modes:
+     *   - 'bundle': Use esbuild + bundleRegistryPlugin to bundle into a single file
+     *   - 'copy':   Directly copy the entire electron/ directory to public/electron/
+     *
+     * Clears the output directory (rm outdir) before bundling to ensure a clean build
+     */
+    bundle(bundleConfig?: BundleConfig): Promise<void>;
+    /**
+     * Resolve the esbuild options shared by the main bundle and the per-file copy transpile.
+     *
+     * Both the bundled main.js and the separately-transpiled jobs/copy files must use identical
+     * compilation settings, otherwise main process code and job code would diverge (e.g. main.js
+     * minified but jobs not, or different module format / target / define). This method centralizes
+     * everything that should be consistent; callers add only the mode-specific keys (bundle,
+     * entryPoints/outfile, externals, plugins, banner, logLevel).
+     *
+     * sourcemap auto mode: dev → inline (debuggable), prod → off (smaller output).
+     */
+    private _resolveBaseBuildOptions;
+    /**
+     * Bundle Electron code using esbuild + registry plugin
+     *
+     * esbuild configuration strategy:
+     *   - entryPoints: Virtual module 'app:bundle-entry' (generated by the plugin)
+     *   - format: Default cjs (recommended for Electron), optional esm
+     *   - sourcemap: Auto-inferred (dev→inline, prod→off), user can override
+     *   - external: Framework externals (ee-core/electron/better-sqlite3 etc.) + user-defined
+     *   - banner: Injects process.env.EE_BUNDLED = "true" so ee-core detects bundle mode
+     *   - packages: 'external' tells esbuild to automatically exclude all node_modules packages
+     *
+     * Post-bundle steps:
+     *   1. Rename output file (app_bundle-entry.js → main.js)
+     *   2. Copy non-bundlable files (jobs directory, preload/bridge.js, user-defined copy targets)
+     */
+    private _bundleWithRegistry;
+    /**
+     * Copy a directory or single file from electron/ to the bundle output WITH per-file transpilation.
+     *
+     * Script files (.ts/.js/.mts/.cts/.tsx/.jsx) are compiled to Node-loadable .js using
+     * esbuild with bundle:false, so their imports stay as runtime require()/import calls:
+     *   - relative imports (./foo) resolve to the sibling transpiled .js
+     *   - ee-core/* and other packages resolve from node_modules at runtime
+     * Non-script files (e.g. .json) are copied verbatim. Directory structure is preserved.
+     *
+     * @param src        Absolute path to a source directory or file
+     * @param dest       Absolute path to the destination directory (for a dir src) or file (for a file src)
+     * @param baseOptions Shared esbuild options from _resolveBaseBuildOptions — same compilation
+     *                    settings (format/target/minify/define/...) as the main bundle, so copied
+     *                    code stays consistent with main.js. bundle:false is forced for per-file output.
+     */
+    private _transpileDir;
+    /**
+     * Copy non-bundlable files — two-tier strategy
+     *
+     * 1. preload/bridge.js (BrowserWindow preload script must be a separate file, loaded directly by Electron)
+     * 2. Copy targets: framework defaults (jobs/) + user-defined (bundleConfig.copy), all handled
+     *    per-file by _transpileDir — script files transpiled to CJS .js (so Node's require()/
+     *    child_process.fork() can load them), other files copied verbatim, structure preserved
+     */
+    private _copyUnbundledFiles;
+    /**
+     * Switch package.json main field
+     *
+     * After bundling, Electron needs to point to ./public/electron/main.js instead of
+     * ./electron/main.js, because the bundle output is in the public/electron/ directory.
+     * The original value is saved before switching so it can be restored later.
+     */
+    private _switchPkgMain;
+    /**
+     * Restore package.json main field
+     *
+     * Restores the original main value after build completes or on SIGINT/SIGTERM,
+     * preventing package.json from being permanently modified (which would break dev mode)
+     */
+    private _restorePkgMain;
 }
 export declare const serveProcess: ServeProcess;
 export { ServeProcess };

package/dist/esm/tools/serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../../src/tools/serve.ts"],"names":[],"mappings":"AAOA,OAAO,UAAsC,MAAM,aAAa,CAAC;AAKjE,UAAU,UAAU;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,UAAU,YAAY;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,cAAM,YAAY;IAChB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;;IAUhB,KAAK,IAAI,IAAI;IAYP,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBpC,GAAG,CAAC,OAAO,GAAE,YAAiB,GAAG,IAAI;IAgErC,KAAK,CAAC,OAAO,GAAE,YAAiB,GAAG,IAAI;IAiBvC,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhC,KAAK,CAAC,OAAO,GAAE,YAAiB,GAAG,IAAI;IAgCvC,IAAI,CAAC,OAAO,GAAE,YAAiB,GAAG,IAAI;IActC,SAAS,CAAC,GAAG,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IA4DnG,MAAM,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAkBpD,cAAc,CAAC,UAAU,UAAQ,GAAG,IAAI;CAsBvC;AAEH,eAAO,MAAM,YAAY,cAAqB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../../src/tools/serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AASH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAI7C,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAUnE,wFAAwF;AACxF,UAAU,YAAY;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,cAAM,YAAY;IAChB,2IAA2I;IAC3I,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC1C,qFAAqF;IACrF,OAAO,CAAC,eAAe,CAAqB;;IAQ5C,kHAAkH;IAClH,OAAO,CAAC,KAAK;IAYb;;;;;;;OAOG;YACW,aAAa;IAgB3B;;;;;;;;;;;;OAYG;IACG,GAAG,CAAC,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAuEpD;;;OAGG;IACG,KAAK,CAAC,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBtD,6DAA6D;IAC7D,OAAO,CAAC,KAAK;IAIb;;;;;;;;;;;OAWG;IACG,KAAK,CAAC,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCtD,0EAA0E;IAC1E,IAAI,CAAC,OAAO,GAAE,YAAiB,GAAG,IAAI;IActC;;;;;;;;OAQG;IACH,SAAS,CAAC,GAAG,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IA4E/G;;;;;;;;OAQG;IACG,MAAM,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAexD;;;;;;;;;;OAUG;IACH,OAAO,CAAC,wBAAwB;IA4BhC;;;;;;;;;;;;;;OAcG;YACW,mBAAmB;IA6EjC;;;;;;;;;;;;;;OAcG;YACW,aAAa;IAqC3B;;;;;;;OAOG;YACW,mBAAmB;IAiCjC;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAYtB;;;;;OAKG;IACH,OAAO,CAAC,eAAe;CAUxB;AAED,eAAO,MAAM,YAAY,cAAqB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,CAAC"}