ee-core 5.0.0-beta.2 → 5.0.0-beta.6

package/README.md

@@ -0,0 +1,178 @@
+# ee-core
+
+Enterprise-grade Electron application framework core — TypeScript edition with dual CJS + ESM module support.
+
+## Overview
+
+`ee-core` provides the runtime foundation for [electron-egg](https://github.com/wallace5303/electron-egg) applications. It handles the complete lifecycle from boot to shutdown: configuration loading, controller registration, IPC communication, window management, logging, storage, background jobs, and cross-process coordination.
+
+The package outputs dual module formats (CJS + ESM) via conditional exports in `package.json`, making it compatible with both `require()` and `import` environments.
+
+## Installation
+
+```bash
+npm install ee-core
+```
+
+## Subpath Exports
+
+ee-core exposes fine-grained subpath modules. Each can be imported individually:
+
+```ts
+// Main entry (boot, app, config, etc.)
+import { ElectronEgg } from 'ee-core';
+
+// Specific submodules
+import { ControllerLoader } from 'ee-core/controller';
+import { Cross, cross } from 'ee-core/cross';
+import { extend } from 'ee-core/utils';
+import { SqliteStorage } from 'ee-core/storage';
+import { ChildJob, ChildPoolJob, LoadBalancer } from 'ee-core/jobs';
+import type { Config, DevConfig } from 'ee-core/types';
+```
+
+Available subpaths:
+
+| Subpath | Description |
+|---|---|
+| `ee-core` | Main entry — boot, application, config, events |
+| `ee-core/app` | Application lifecycle and event bus |
+| `ee-core/config` | Configuration loading and merging |
+| `ee-core/controller` | Controller loader and registry |
+| `ee-core/core` | FileLoader and core utilities |
+| `ee-core/cross` | IPC communication (socket.io, HTTP, Electron IPC) |
+| `ee-core/electron` | Electron app/window management |
+| `ee-core/exception` | Exception handling |
+| `ee-core/html` | HTML static resource path utility |
+| `ee-core/jobs` | Background jobs (ChildJob, ChildPoolJob, LoadBalancer) |
+| `ee-core/loader` | File/module loading utilities |
+| `ee-core/log` | Pino-based logging (pino-roll + pino-pretty) |
+| `ee-core/message` | IPC message routing |
+| `ee-core/ps` | Process/environment utilities (paths, env detection) |
+| `ee-core/socket` | Socket.IO, HTTP, IPC servers |
+| `ee-core/storage` | SQLite storage (better-sqlite3) |
+| `ee-core/types` | TypeScript type definitions |
+| `ee-core/utils` | extend, is, json, helper, pargv, port |
+
+## Architecture
+
+### Lifecycle
+
+Boot → loadConfig → loadLog → loadDir → loadController → loadSocket → loadElectron
+
+### Controller Loading Pipeline
+
+- **Build time** (ee-bin): `controllerRegistryPlugin` scans `electron/controller/`, generates `ee-core:controller-registry` virtual module with lazy getters.
+- **Runtime** (ee-core): If `globalThis.__EE_CONTROLLER_REGISTRY__` exists (bundle mode), loads from registry. Otherwise falls back to filesystem scanning via globby.
+
+### IPC Communication
+
+Main ↔ renderer via `ee-core/cross`, supporting three transport modes:
+- Socket.IO (bidirectional real-time)
+- HTTP server (RESTful)
+- Electron IPC (native)
+
+Channels follow pattern `controller/{name}/{method}`.
+
+### Window Loading Strategy
+
+- Remote mode → Load remote URL
+- Dev mode → Wait for frontend dev server, show loading page first
+- Prod + cross takeover → Wait for cross-process service
+- Prod (default) → Load local HTML file
+
+## Key APIs
+
+### Boot & Application
+
+```ts
+import { ElectronEgg } from 'ee-core';
+
+// Start the framework
+const app = new ElectronEgg();
+```
+
+### Configuration
+
+```ts
+import { getConfig, setConfig } from 'ee-core/config';
+
+const config = getConfig();
+```
+
+### Controller
+
+```ts
+import { getController } from 'ee-core/controller';
+
+const userController = getController('user');
+```
+
+### Cross-Process Communication
+
+```ts
+import { cross } from 'ee-core/cross';
+
+// Send IPC message to renderer
+cross.sendToRenderer('controller/user/info', data);
+```
+
+### Jobs
+
+```ts
+import { ChildJob, ChildPoolJob, LoadBalancer } from 'ee-core/jobs';
+
+const job = new ChildJob();
+const result = await job.exec({ name: 'task', script: './jobs/demo.js' });
+```
+
+### Storage
+
+```ts
+import { SqliteStorage } from 'ee-core/storage';
+
+const db = new SqliteStorage('./data/app.db');
+db.prepare('CREATE TABLE IF NOT EXISTS user (id INTEGER PRIMARY KEY, name TEXT)').run();
+```
+
+### Logging
+
+```ts
+import { coreLogger, getLoggers } from 'ee-core/log';
+
+coreLogger.info('Application started');
+```
+
+### Process/Environment
+
+```ts
+import { isDev, getBaseDir, env } from 'ee-core/ps';
+
+if (isDev()) {
+  // Development-specific logic
+}
+```
+
+## Build
+
+```bash
+npm run build          # Build CJS + ESM + generate exports map
+npm run build:cjs      # Build CommonJS only
+npm run build:esm      # Build ESM only
+npm run typecheck      # TypeScript type checking
+npm run test           # Run vitest
+```
+
+The `exports` map in `package.json` is auto-generated by `scripts/gen-exports.js`. Do not edit manually — run `npm run gen-exports` after adding new subpath modules.
+
+## Requirements
+
+- Node.js >= 20.19.0
+- Electron >= 28
+- Better-sqlite3 requires native rebuild for Electron: use `pnpm re-sqlite` if you see native module errors
+
+## Notes
+
+- ESM imports in ee-core source must include `.js` extensions (required by `module: NodeNext`)
+- ee-core is NOT bundled into the Electron main process bundle — it's an esbuild external loaded from `node_modules` at runtime
+- The framework uses the `debug` library for verbose logging. Enable with `DEBUG=ee-*` environment variable

package/dist/cjs/app/application.d.ts

@@ -1,6 +1,41 @@
+/**
+ * Application class — Framework startup flow orchestrator
+ *
+ * Responsibilities:
+ * - register(): Register lifecycle event hooks
+ * - run(): Synchronous startup flow (CJS controller loading)
+ * - runAsync(): Asynchronous startup flow (ESM controller loading)
+ *
+ * Startup order:
+ * 1. Load Controllers — Register all business handler functions
+ * 2. Load Communication Services (Socket) — Start IPC/HTTP/SocketIO services
+ * 3. Emit Ready lifecycle event
+ * 4. Load Electron features — Create windows, register shortcuts, etc.
+ */
 export declare class Application {
+    /**
+     * Register a lifecycle event handler
+     * @param eventName - Event name (e.g. 'ready', 'before-close')
+     * @param handler - Event handler function
+     */
     register(eventName: string, handler: (...args: unknown[]) => void): void;
-    run(): void;
+    /**
+     * Start the application synchronously
+     *
+     * Flow:
+     * 1. loadController() — Synchronously load controllers (using require())
+     * 2. loadSocket() — Start IPC/HTTP/SocketIO communication services
+     * 3. emitLifecycle(Ready) — Trigger ready lifecycle event
+     * 4. loadElectron() — Initialize Electron main process (create windows, etc.)
+     */
+    run(): Promise<void>;
+    /**
+     * Start the application asynchronously
+     *
+     * Same flow as run(), but controllers are loaded asynchronously using dynamic import(), supporting ESM modules.
+     */
+    runAsync(): Promise<void>;
 }
+/** Application singleton */
 export declare const app: Application;
 //# sourceMappingURL=application.d.ts.map

package/dist/cjs/app/application.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"application.d.ts","sourceRoot":"","sources":["../../../src/app/application.ts"],"names":[],"mappings":"AAKA,qBAAa,WAAW;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI;IAIxE,GAAG,IAAI,IAAI;CAMZ;AAED,eAAO,MAAM,GAAG,aAAoB,CAAC"}
+{"version":3,"file":"application.d.ts","sourceRoot":"","sources":["../../../src/app/application.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAW;IACtB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI;IAIxE;;;;;;;;OAQG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAO1B;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAMhC;AAED,4BAA4B;AAC5B,eAAO,MAAM,GAAG,aAAoB,CAAC"}

package/dist/cjs/app/application.js

@@ -1,21 +1,68 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.app = exports.Application = void 0;
+/**
+ * @module app/application
+ * @description Application core class that orchestrates the framework startup flow.
+ * Responsible for sequentially loading controllers, communication services,
+ * emitting lifecycle events, and finally loading Electron main process features.
+ * Held and invoked by the ElectronEgg class in boot.ts.
+ */
 const index_js_1 = require("../controller/index.js");
 const events_js_1 = require("./events.js");
 const index_js_2 = require("../socket/index.js");
 const index_js_3 = require("../electron/index.js");
+/**
+ * Application class — Framework startup flow orchestrator
+ *
+ * Responsibilities:
+ * - register(): Register lifecycle event hooks
+ * - run(): Synchronous startup flow (CJS controller loading)
+ * - runAsync(): Asynchronous startup flow (ESM controller loading)
+ *
+ * Startup order:
+ * 1. Load Controllers — Register all business handler functions
+ * 2. Load Communication Services (Socket) — Start IPC/HTTP/SocketIO services
+ * 3. Emit Ready lifecycle event
+ * 4. Load Electron features — Create windows, register shortcuts, etc.
+ */
 class Application {
+    /**
+     * Register a lifecycle event handler
+     * @param eventName - Event name (e.g. 'ready', 'before-close')
+     * @param handler - Event handler function
+     */
     register(eventName, handler) {
         events_js_1.eventBus.register(eventName, handler);
     }
-    run() {
+    /**
+     * Start the application synchronously
+     *
+     * Flow:
+     * 1. loadController() — Synchronously load controllers (using require())
+     * 2. loadSocket() — Start IPC/HTTP/SocketIO communication services
+     * 3. emitLifecycle(Ready) — Trigger ready lifecycle event
+     * 4. loadElectron() — Initialize Electron main process (create windows, etc.)
+     */
+    async run() {
         (0, index_js_1.loadController)();
-        (0, index_js_2.loadSocket)();
+        await (0, index_js_2.loadSocket)();
+        events_js_1.eventBus.emitLifecycle(events_js_1.Ready);
+        (0, index_js_3.loadElectron)();
+    }
+    /**
+     * Start the application asynchronously
+     *
+     * Same flow as run(), but controllers are loaded asynchronously using dynamic import(), supporting ESM modules.
+     */
+    async runAsync() {
+        await (0, index_js_1.loadControllerAsync)();
+        await (0, index_js_2.loadSocket)();
         events_js_1.eventBus.emitLifecycle(events_js_1.Ready);
         (0, index_js_3.loadElectron)();
     }
 }
 exports.Application = Application;
+/** Application singleton */
 exports.app = new Application();
 //# sourceMappingURL=application.js.map

package/dist/cjs/app/application.js.map

@@ -1 +1 @@
-{"version":3,"file":"application.js","sourceRoot":"","sources":["../../../src/app/application.ts"],"names":[],"mappings":";;;AAAA,qDAAwD;AACxD,2CAA8C;AAC9C,iDAAgD;AAChD,mDAAoD;AAEpD,MAAa,WAAW;IACtB,QAAQ,CAAC,SAAiB,EAAE,OAAqC;QAC/D,oBAAQ,CAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACxC,CAAC;IAED,GAAG;QACD,IAAA,yBAAc,GAAE,CAAC;QACjB,IAAA,qBAAU,GAAE,CAAC;QACb,oBAAQ,CAAC,aAAa,CAAC,iBAAK,CAAC,CAAC;QAC9B,IAAA,uBAAY,GAAE,CAAC;IACjB,CAAC;CACF;AAXD,kCAWC;AAEY,QAAA,GAAG,GAAG,IAAI,WAAW,EAAE,CAAC"}
+{"version":3,"file":"application.js","sourceRoot":"","sources":["../../../src/app/application.ts"],"names":[],"mappings":";;;AAAA;;;;;;GAMG;AACH,qDAA6E;AAC7E,2CAA8C;AAC9C,iDAAgD;AAChD,mDAAoD;AAEpD;;;;;;;;;;;;;GAaG;AACH,MAAa,WAAW;IACtB;;;;OAIG;IACH,QAAQ,CAAC,SAAiB,EAAE,OAAqC;QAC/D,oBAAQ,CAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACxC,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,GAAG;QACP,IAAA,yBAAc,GAAE,CAAC;QACjB,MAAM,IAAA,qBAAU,GAAE,CAAC;QACnB,oBAAQ,CAAC,aAAa,CAAC,iBAAK,CAAC,CAAC;QAC9B,IAAA,uBAAY,GAAE,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ;QACZ,MAAM,IAAA,8BAAmB,GAAE,CAAC;QAC5B,MAAM,IAAA,qBAAU,GAAE,CAAC;QACnB,oBAAQ,CAAC,aAAa,CAAC,iBAAK,CAAC,CAAC;QAC9B,IAAA,uBAAY,GAAE,CAAC;IACjB,CAAC;CACF;AArCD,kCAqCC;AAED,4BAA4B;AACf,QAAA,GAAG,GAAG,IAAI,WAAW,EAAE,CAAC"}

package/dist/cjs/app/boot.d.ts

@@ -1,9 +1,64 @@
 import type { ElectronEggOptions } from '../types/index.js';
+/**
+ * ElectronEgg framework main class
+ *
+ * Responsibilities:
+ * 1. Collect Electron runtime environment info (app name, version, paths, etc.)
+ * 2. Set global environment variables (EE_ENV, EE_BASE_DIR, etc.)
+ * 3. Initialize framework foundational features (exception handling -> config -> directories -> logging)
+ * 4. Provide register() for lifecycle hooks, run()/runAsync() to start the application
+ *
+ * Usage:
+ * ```ts
+ * const electronEgg = new ElectronEgg();
+ * electronEgg.register('ready', () => { ... });
+ * await electronEgg.run();
+ * ```
+ */
 export declare class ElectronEgg {
     options: ElectronEggOptions;
+    /**
+     * Constructor — Collects environment info and initializes the framework
+     *
+     * Execution flow:
+     * 1. Get Electron app path as baseDir
+     * 2. Parse command-line arguments: env (environment) and debugger (debug source flag)
+     * 3. Based on debugger flag, decide whether electronDir points to bundle output or source directory
+     * 4. Collect application info (name, version, paths, etc.) to build options
+     * 5. In production + packaged mode, execDir points to the executable's directory
+     * 6. Write key info to process.env for other modules to read
+     * 7. Call init() to load foundational features
+     */
     constructor();
+    /**
+     * Initialize framework foundational features
+     *
+     * Loading order (must not be changed):
+     * 1. loadException — Register global exception handling to ensure subsequent exceptions are caught
+     * 2. loadConfig — Load configuration files; subsequent modules depend on configuration
+     * 3. loadDir — Create necessary directories for data/logs
+     * 4. loadLog — Initialize logging system; depends on configuration and directories
+     */
     init(): void;
+    /**
+     * Register a lifecycle event handler
+     * @param eventName - Lifecycle event name (e.g. 'ready', 'electron-app-ready')
+     * @param handler - Event handler function
+     */
     register(eventName: string, handler: (...args: unknown[]) => void): void;
-    run(): void;
+    /**
+     * Start the application synchronously
+     *
+     * Execution flow: loadController -> loadSocket -> emitLifecycle(ready) -> loadElectron
+     * Controllers are loaded using synchronous require(), suitable for CJS projects
+     */
+    run(): Promise<void>;
+    /**
+     * Start the application asynchronously
+     *
+     * Execution flow: loadControllerAsync -> loadSocket -> emitLifecycle(ready) -> loadElectron
+     * Controllers are loaded using dynamic import(), suitable for ESM projects
+     */
+    runAsync(): Promise<void>;
 }
 //# sourceMappingURL=boot.d.ts.map

package/dist/cjs/app/boot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"boot.d.ts","sourceRoot":"","sources":["../../../src/app/boot.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAI5D,qBAAa,WAAW;IACtB,OAAO,EAAE,kBAAkB,CAAC;;IAkD5B,IAAI,IAAI,IAAI;IAQZ,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI;IAIxE,GAAG,IAAI,IAAI;CAGZ"}
+{"version":3,"file":"boot.d.ts","sourceRoot":"","sources":["../../../src/app/boot.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAI5D;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,WAAW;IACtB,OAAO,EAAE,kBAAkB,CAAC;IAE5B;;;;;;;;;;;OAWG;;IAiDH;;;;;;;;OAQG;IACH,IAAI,IAAI,IAAI;IAOZ;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI;IAIxE;;;;;OAKG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAI1B;;;;;OAKG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAGhC"}

package/dist/cjs/app/boot.js

@@ -4,6 +4,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ElectronEgg = void 0;
+/**
+ * @module app/boot
+ * @description ElectronEgg framework boot module. Responsible for initializing the runtime environment,
+ * collecting application configuration, setting global environment variables, and sequentially
+ * loading framework foundational features (exception handling, configuration, directories, logging).
+ * This is the entry class of the entire framework, instantiated and started via run() from electron/main.js.
+ */
 const debug_1 = __importDefault(require("debug"));
 const path_1 = __importDefault(require("path"));
 const index_js_1 = require("../exception/index.js");
@@ -14,18 +21,46 @@ const index_js_5 = require("../log/index.js");
 const application_js_1 = require("./application.js");
 const dir_js_1 = require("./dir.js");
 const debugLog = (0, debug_1.default)('ee-core:app:boot');
+/**
+ * ElectronEgg framework main class
+ *
+ * Responsibilities:
+ * 1. Collect Electron runtime environment info (app name, version, paths, etc.)
+ * 2. Set global environment variables (EE_ENV, EE_BASE_DIR, etc.)
+ * 3. Initialize framework foundational features (exception handling -> config -> directories -> logging)
+ * 4. Provide register() for lifecycle hooks, run()/runAsync() to start the application
+ *
+ * Usage:
+ * ```ts
+ * const electronEgg = new ElectronEgg();
+ * electronEgg.register('ready', () => { ... });
+ * await electronEgg.run();
+ * ```
+ */
 class ElectronEgg {
+    /**
+     * Constructor — Collects environment info and initializes the framework
+     *
+     * Execution flow:
+     * 1. Get Electron app path as baseDir
+     * 2. Parse command-line arguments: env (environment) and debugger (debug source flag)
+     * 3. Based on debugger flag, decide whether electronDir points to bundle output or source directory
+     * 4. Collect application info (name, version, paths, etc.) to build options
+     * 5. In production + packaged mode, execDir points to the executable's directory
+     * 6. Write key info to process.env for other modules to read
+     * 7. Call init() to load foundational features
+     */
     constructor() {
         const baseDir = index_js_2.electronApp.getAppPath();
-        const environmet = (0, index_js_3.getArgumentByName)('env') || 'prod';
-        const debugging = (0, index_js_3.getArgumentByName)('debuger') === 'true';
-        // Debugging source code
+        const environment = (0, index_js_3.getArgumentByName)('env') || 'prod';
+        const debugging = (0, index_js_3.getArgumentByName)('debugger') === 'true';
+        // In debug mode, point to source directory; otherwise point to bundle output directory
         let electronDir = (0, index_js_3.getBundleDir)(baseDir);
         if (debugging) {
             electronDir = (0, index_js_3.getElectronCodeDir)(baseDir);
         }
         const options = {
-            env: environmet,
+            env: environment,
             baseDir,
             electronDir,
             appName: index_js_2.electronApp.getName(),
@@ -36,12 +71,12 @@ class ElectronEgg {
             isPackaged: index_js_2.electronApp.isPackaged,
             execDir: baseDir,
         };
-        // exec directory (exe dmg dep) for prod
-        if (environmet === 'prod' && options.isPackaged) {
+        // In production and packaged mode, execDir is the directory of the executable (same level as exe/dmg)
+        if (environment === 'prod' && options.isPackaged) {
             options.execDir = path_1.default.dirname(index_js_2.electronApp.getPath('exe'));
         }
-        // normalize env
-        process.env.EE_ENV = environmet;
+        // Write runtime environment info to global variables for use by config loading, logging, and other modules
+        process.env.EE_ENV = environment;
         process.env.EE_APP_NAME = options.appName;
         process.env.EE_APP_VERSION = options.appVersion;
         process.env.EE_BASE_DIR = options.baseDir;
@@ -57,18 +92,46 @@ class ElectronEgg {
         this.options = options;
         this.init();
     }
+    /**
+     * Initialize framework foundational features
+     *
+     * Loading order (must not be changed):
+     * 1. loadException — Register global exception handling to ensure subsequent exceptions are caught
+     * 2. loadConfig — Load configuration files; subsequent modules depend on configuration
+     * 3. loadDir — Create necessary directories for data/logs
+     * 4. loadLog — Initialize logging system; depends on configuration and directories
+     */
     init() {
-        // basic functions
         (0, index_js_1.loadException)();
         (0, index_js_4.loadConfig)();
         (0, dir_js_1.loadDir)();
         (0, index_js_5.loadLog)();
     }
+    /**
+     * Register a lifecycle event handler
+     * @param eventName - Lifecycle event name (e.g. 'ready', 'electron-app-ready')
+     * @param handler - Event handler function
+     */
     register(eventName, handler) {
         application_js_1.app.register(eventName, handler);
     }
-    run() {
-        application_js_1.app.run();
+    /**
+     * Start the application synchronously
+     *
+     * Execution flow: loadController -> loadSocket -> emitLifecycle(ready) -> loadElectron
+     * Controllers are loaded using synchronous require(), suitable for CJS projects
+     */
+    async run() {
+        await application_js_1.app.run();
+    }
+    /**
+     * Start the application asynchronously
+     *
+     * Execution flow: loadControllerAsync -> loadSocket -> emitLifecycle(ready) -> loadElectron
+     * Controllers are loaded using dynamic import(), suitable for ESM projects
+     */
+    async runAsync() {
+        await application_js_1.app.runAsync();
     }
 }
 exports.ElectronEgg = ElectronEgg;

package/dist/cjs/app/boot.js.map

@@ -1 +1 @@
-{"version":3,"file":"boot.js","sourceRoot":"","sources":["../../../src/app/boot.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"boot.js","sourceRoot":"","sources":["../../../src/app/boot.ts"],"names":[],"mappings":"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"}

package/dist/cjs/app/dir.d.ts

@@ -1,2 +1,12 @@
+/**
+ * Load and initialize directories required for application runtime
+ *
+ * Creates the following directories (if they don't exist):
+ * - Hidden app directory under user home (~/.{appName}/) — Stores app-level configuration and cache
+ * - Data directory — Stores business data (e.g. SQLite database files)
+ * - Log directory — Stores runtime log files
+ *
+ * Directory permissions set to 0o755 (owner: read/write/execute; others: read/execute)
+ */
 export declare function loadDir(): void;
 //# sourceMappingURL=dir.d.ts.map

package/dist/cjs/app/dir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dir.d.ts","sourceRoot":"","sources":["../../../src/app/dir.ts"],"names":[],"mappings":"AAIA,wBAAgB,OAAO,IAAI,IAAI,CAE9B"}
+{"version":3,"file":"dir.d.ts","sourceRoot":"","sources":["../../../src/app/dir.ts"],"names":[],"mappings":"AAWA;;;;;;;;;GASG;AACH,wBAAgB,OAAO,IAAI,IAAI,CAE9B"}

package/dist/cjs/app/dir.js

@@ -1,27 +1,88 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadDir = loadDir;
+/**
+ * @module app/dir
+ * @description Application directory initialization module. Creates necessary runtime directories
+ * at framework startup, including the hidden app directory under the user's home directory
+ * (for storing configuration, etc.), data directory, and log directory.
+ */
 const fs_1 = __importDefault(require("fs"));
 const index_js_1 = require("../ps/index.js");
 const helper_js_1 = require("../utils/helper.js");
+const is = __importStar(require("../utils/is.js"));
+/**
+ * Load and initialize directories required for application runtime
+ *
+ * Creates the following directories (if they don't exist):
+ * - Hidden app directory under user home (~/.{appName}/) — Stores app-level configuration and cache
+ * - Data directory — Stores business data (e.g. SQLite database files)
+ * - Log directory — Stores runtime log files
+ *
+ * Directory permissions set to 0o755 (owner: read/write/execute; others: read/execute)
+ */
 function loadDir() {
     initDir();
 }
 function initDir() {
-    const homeHiddenAppDir = (0, index_js_1.getUserHomeHiddenAppDir)();
-    if (!fs_1.default.existsSync(homeHiddenAppDir)) {
-        (0, helper_js_1.mkdir)(homeHiddenAppDir, { mode: 0o755 });
-    }
-    const dataDir = (0, index_js_1.getDataDir)();
-    if (!fs_1.default.existsSync(dataDir)) {
-        (0, helper_js_1.mkdir)(dataDir, { mode: 0o755 });
+    // 在记录日志前，单独捕获异常
+    try {
+        // 初始化应用自定义数据目录
+        let customAppDir = (0, index_js_1.getUserHomeHiddenAppDir)();
+        // 权限问题，openharmony 环境下，自定义应用目录
+        if (is.openharmony()) {
+            customAppDir = (0, index_js_1.getAppCustomDataDir)();
+        }
+        if (!fs_1.default.existsSync(customAppDir)) {
+            (0, helper_js_1.mkdir)(customAppDir, { mode: 0o755 });
+        }
+        const dataDir = (0, index_js_1.getDataDir)();
+        if (!fs_1.default.existsSync(dataDir)) {
+            (0, helper_js_1.mkdir)(dataDir, { mode: 0o755 });
+        }
+        const logDir = (0, index_js_1.getLogDir)();
+        if (!fs_1.default.existsSync(logDir)) {
+            (0, helper_js_1.mkdir)(logDir, { mode: 0o755 });
+        }
     }
-    const logDir = (0, index_js_1.getLogDir)();
-    if (!fs_1.default.existsSync(logDir)) {
-        (0, helper_js_1.mkdir)(logDir, { mode: 0o755 });
+    catch (e) {
+        console.error('[dir] initDir error: %s', e instanceof Error ? e.message : String(e));
     }
 }
 //# sourceMappingURL=dir.js.map

package/dist/cjs/app/dir.js.map

@@ -1 +1 @@
-{"version":3,"file":"dir.js","sourceRoot":"","sources":["../../../src/app/dir.ts"],"names":[],"mappings":";;;;;AAIA,0BAEC;AAND,4CAAoB;AACpB,6CAAgF;AAChF,kDAA2C;AAE3C,SAAgB,OAAO;IACrB,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,OAAO;IACd,MAAM,gBAAgB,GAAG,IAAA,kCAAuB,GAAE,CAAC;IACnD,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,gBAAgB,CAAC,EAAE,CAAC;QACrC,IAAA,iBAAK,EAAC,gBAAgB,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3C,CAAC;IACD,MAAM,OAAO,GAAG,IAAA,qBAAU,GAAE,CAAC;IAC7B,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,IAAA,iBAAK,EAAC,OAAO,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAClC,CAAC;IACD,MAAM,MAAM,GAAG,IAAA,oBAAS,GAAE,CAAC;IAC3B,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,IAAA,iBAAK,EAAC,MAAM,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACjC,CAAC;AACH,CAAC"}
+{"version":3,"file":"dir.js","sourceRoot":"","sources":["../../../src/app/dir.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqBA,0BAEC;AAvBD;;;;;GAKG;AACH,4CAAoB;AACpB,6CAAqG;AACrG,kDAA2C;AAC3C,mDAAqC;AAErC;;;;;;;;;GASG;AACH,SAAgB,OAAO;IACrB,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,OAAO;IACd,gBAAgB;IAChB,IAAI,CAAC;QACH,eAAe;QACf,IAAI,YAAY,GAAG,IAAA,kCAAuB,GAAE,CAAC;QAC7C,+BAA+B;QAC/B,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC;YACrB,YAAY,GAAG,IAAA,8BAAmB,GAAE,CAAC;QACvC,CAAC;QACD,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YACjC,IAAA,iBAAK,EAAC,YAAY,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACvC,CAAC;QACD,MAAM,OAAO,GAAG,IAAA,qBAAU,GAAE,CAAC;QAC7B,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,IAAA,iBAAK,EAAC,OAAO,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAClC,CAAC;QACD,MAAM,MAAM,GAAG,IAAA,oBAAS,GAAE,CAAC;QAC3B,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,IAAA,iBAAK,EAAC,MAAM,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAAC,OAAO,CAAU,EAAE,CAAC;QACpB,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IACvF,CAAC;AACH,CAAC"}