@majkapp/plugin-kit 1.0.7 → 1.0.9

package/dist/plugin-kit.d.ts

@@ -33,6 +33,18 @@ export interface FluentBuilder<Id extends string> {
     onReady(fn: (ctx: PluginContext, cleanup: (fn: CleanupFn) => void) => void | Promise<void>): this;
     /** Custom health check */
     health(fn: HealthCheckFn): this;
+    /**
+     * Set the plugin root directory explicitly (use __dirname from your plugin entry file).
+     * This ensures plugin-kit can find your files in both local development and npm installed scenarios.
+     * If not provided, falls back to the pluginRoot from MAJK's context.
+     *
+     * @example
+     * const plugin = definePlugin('my-plugin', 'My Plugin', '1.0.0')
+     *   .pluginRoot(__dirname)  // Use Node's __dirname
+     *   .ui({ appDir: 'dist' }) // Now resolves relative to __dirname
+     *   .build();
+     */
+    pluginRoot(dir: string): this;
     /** Build the plugin */
     build(): InProcessPlugin;
 }

package/dist/plugin-kit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-kit.d.ts","sourceRoot":"","sources":["../src/plugin-kit.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,aAAa,EAGb,eAAe,EACf,QAAQ,EACR,WAAW,EACX,WAAW,EACX,QAAQ,EACR,WAAW,EACX,UAAU,EACV,eAAe,EACf,WAAW,EACX,KAAK,EACL,UAAU,EACV,SAAS,EACT,aAAa,EAIb,eAAe,EACf,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAgqBjB;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,EAAE,SAAS,MAAM;IAC9C,mDAAmD;IACnD,MAAM,CAAC,KAAK,EAAE,mBAAmB,EAAE,IAAI,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAE7G,0CAA0C;IAC1C,EAAE,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAE5B,yBAAyB;IACzB,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IAE3C,yBAAyB;IACzB,UAAU,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IAEzC,uBAAuB;IACvB,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAEnC,iBAAiB;IACjB,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAE/D,oEAAoE;IACpE,MAAM,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAEtD,8DAA8D;IAC9D,SAAS,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,IAAI,CAAC;IAE5C,+DAA+D;IAC/D,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC;IAE9C,wBAAwB;IACxB,YAAY,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,CAAC;IAEzC,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;IAEjC,sCAAsC;IACtC,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,IAAI,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAElG,0BAA0B;IAC1B,MAAM,CAAC,EAAE,EAAE,aAAa,GAAG,IAAI,CAAC;IAEhC,uBAAuB;IACvB,KAAK,IAAI,eAAe,CAAC;CAC1B;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAClD,EAAE,EAAE,EAAE,EACN,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,aAAa,CAAC,EAAE,CAAC,CAoUnB"}
+{"version":3,"file":"plugin-kit.d.ts","sourceRoot":"","sources":["../src/plugin-kit.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,aAAa,EAGb,eAAe,EACf,QAAQ,EACR,WAAW,EACX,WAAW,EACX,QAAQ,EACR,WAAW,EACX,UAAU,EACV,eAAe,EACf,WAAW,EACX,KAAK,EACL,UAAU,EACV,SAAS,EACT,aAAa,EAIb,eAAe,EACf,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAwsBjB;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,EAAE,SAAS,MAAM;IAC9C,mDAAmD;IACnD,MAAM,CAAC,KAAK,EAAE,mBAAmB,EAAE,IAAI,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAE7G,0CAA0C;IAC1C,EAAE,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAE5B,yBAAyB;IACzB,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IAE3C,yBAAyB;IACzB,UAAU,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IAEzC,uBAAuB;IACvB,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAEnC,iBAAiB;IACjB,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAE/D,oEAAoE;IACpE,MAAM,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAEtD,8DAA8D;IAC9D,SAAS,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,IAAI,CAAC;IAE5C,+DAA+D;IAC/D,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC;IAE9C,wBAAwB;IACxB,YAAY,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,CAAC;IAEzC,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;IAEjC,sCAAsC;IACtC,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,IAAI,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAElG,0BAA0B;IAC1B,MAAM,CAAC,EAAE,EAAE,aAAa,GAAG,IAAI,CAAC;IAEhC;;;;;;;;;;OAUG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9B,uBAAuB;IACvB,KAAK,IAAI,eAAe,CAAC;CAC1B;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAClD,EAAE,EAAE,EAAE,EACN,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,aAAa,CAAC,EAAE,CAAC,CAkVnB"}

package/dist/plugin-kit.js

@@ -286,7 +286,7 @@ function serveSpa(ui, req, res, ctx) {
  * Main plugin class built by the fluent API
  */
 class BuiltPlugin {
-    constructor(id, name, version, capabilities, tools, apiRoutes, uiConfig, reactScreens, htmlScreens, wizard, onReadyFn, healthCheckFn) {
+    constructor(id, name, version, capabilities, tools, apiRoutes, uiConfig, reactScreens, htmlScreens, wizard, onReadyFn, healthCheckFn, userProvidedPluginRoot) {
         this.capabilities = capabilities;
         this.tools = tools;
         this.apiRoutes = apiRoutes;
@@ -296,6 +296,7 @@ class BuiltPlugin {
         this.wizard = wizard;
         this.onReadyFn = onReadyFn;
         this.healthCheckFn = healthCheckFn;
+        this.userProvidedPluginRoot = userProvidedPluginRoot;
         this.cleanups = [];
         this.router = [];
         this.id = id;
@@ -334,27 +335,40 @@ class BuiltPlugin {
         };
     }
     async onLoad(context) {
-        this.context = context;
+        // Use user-provided pluginRoot (from __dirname) if available, otherwise fall back to context.pluginRoot
+        // The user-provided path comes from Node's __dirname which automatically resolves to the real directory
+        // (following symlinks), making it work correctly in both local development and npm installed scenarios
+        const effectivePluginRoot = this.userProvidedPluginRoot || context.pluginRoot;
+        this.context = {
+            ...context,
+            pluginRoot: effectivePluginRoot
+        };
         context.logger.info('═══════════════════════════════════════════════════════');
         context.logger.info(`🚀 Loading Plugin: ${this.name} (${this.id}) v${this.version}`);
-        context.logger.info(`📍 Plugin Root: ${context.pluginRoot}`);
+        context.logger.info(`📍 Plugin Root: ${effectivePluginRoot}`);
+        if (this.userProvidedPluginRoot) {
+            context.logger.info(`   (user-provided via .pluginRoot(__dirname))`);
+        }
+        else {
+            context.logger.info(`   (from MAJK context - consider using .pluginRoot(__dirname) for better reliability)`);
+        }
         context.logger.info(`🌐 HTTP Port: ${context.http.port}`);
         context.logger.info(`🔗 Base URL: ${context.http.baseUrl}`);
         context.logger.info('═══════════════════════════════════════════════════════');
         // Validate file paths now that we have pluginRoot context
         if (this.reactScreens.length > 0 && this.uiConfig) {
-            const indexPath = path_1.default.join(context.pluginRoot, this.uiConfig.appDir || '', 'index.html');
+            const indexPath = path_1.default.join(this.context.pluginRoot, this.uiConfig.appDir || '', 'index.html');
             if (!fs_1.default.existsSync(indexPath)) {
-                throw new PluginRuntimeError(`React app not built: ${indexPath} does not exist. Run "npm run build" in your UI directory to build the React app.`, 'onLoad', { appDir: this.uiConfig.appDir, indexPath, pluginRoot: context.pluginRoot });
+                throw new PluginRuntimeError(`React app not built: ${indexPath} does not exist. Run "npm run build" in your UI directory to build the React app.`, 'onLoad', { appDir: this.uiConfig.appDir, indexPath, pluginRoot: this.context.pluginRoot });
             }
             context.logger.info(`✅ React UI found at: ${indexPath}`);
         }
         // Validate HTML screen files
         for (const screen of this.htmlScreens) {
             if ('htmlFile' in screen) {
-                const filePath = path_1.default.join(context.pluginRoot, screen.htmlFile);
+                const filePath = path_1.default.join(this.context.pluginRoot, screen.htmlFile);
                 if (!fs_1.default.existsSync(filePath)) {
-                    throw new PluginRuntimeError(`HTML screen file not found: ${screen.htmlFile}. Create the HTML file at ${filePath} or fix the path.`, 'onLoad', { screen: screen.id, file: screen.htmlFile, resolvedPath: filePath, pluginRoot: context.pluginRoot });
+                    throw new PluginRuntimeError(`HTML screen file not found: ${screen.htmlFile}. Create the HTML file at ${filePath} or fix the path.`, 'onLoad', { screen: screen.id, file: screen.htmlFile, resolvedPath: filePath, pluginRoot: this.context.pluginRoot });
                 }
                 context.logger.info(`✅ HTML screen file found: ${screen.htmlFile}`);
             }
@@ -434,11 +448,18 @@ class BuiltPlugin {
     async startServer() {
         const { port } = this.context.http;
         this.server = http_1.default.createServer(async (req, res) => {
+            const startTime = Date.now();
+            const method = req.method || 'UNKNOWN';
+            const url = req.url || '/';
             try {
+                // Log incoming request
+                this.context.logger.debug(`→ ${method} ${url}`);
                 // CORS preflight
                 if (req.method === 'OPTIONS') {
                     res.writeHead(204, corsHeaders());
                     res.end();
+                    const duration = Date.now() - startTime;
+                    this.context.logger.debug(`← ${method} ${url} 204 (${duration}ms)`);
                     return;
                 }
                 // Health check
@@ -446,6 +467,8 @@ class BuiltPlugin {
                     const health = await this.isHealthy();
                     res.writeHead(200, corsHeaders({ 'Content-Type': 'application/json' }));
                     res.end(JSON.stringify({ ...health, plugin: this.name, version: this.version }));
+                    const duration = Date.now() - startTime;
+                    this.context.logger.debug(`← ${method} ${url} 200 (${duration}ms)`);
                     return;
                 }
                 // HTML screens virtual route
@@ -455,6 +478,8 @@ class BuiltPlugin {
                     if (!screen) {
                         res.writeHead(404, corsHeaders({ 'Content-Type': 'text/plain' }));
                         res.end('HTML screen not found');
+                        const duration = Date.now() - startTime;
+                        this.context.logger.debug(`← ${method} ${url} 404 (${duration}ms)`);
                         return;
                     }
                     res.writeHead(200, corsHeaders({ 'Content-Type': 'text/html; charset=utf-8' }));
@@ -470,6 +495,8 @@ class BuiltPlugin {
                             res.writeHead(403, corsHeaders({ 'Content-Type': 'text/plain' }));
                             res.end('Forbidden');
                             this.context.logger.warn(`Path traversal attempt: ${screen.htmlFile}`);
+                            const duration = Date.now() - startTime;
+                            this.context.logger.debug(`← ${method} ${url} 403 (${duration}ms)`);
                             return;
                         }
                         try {
@@ -479,13 +506,20 @@ class BuiltPlugin {
                             this.context.logger.error(`Failed to read HTML file: ${error.message}`);
                             res.writeHead(500, corsHeaders({ 'Content-Type': 'text/html' }));
                             res.end('<!doctype html><html><body><h1>Error loading screen</h1></body></html>');
+                            const duration = Date.now() - startTime;
+                            this.context.logger.debug(`← ${method} ${url} 500 (${duration}ms)`);
+                            return;
                         }
                     }
+                    const duration = Date.now() - startTime;
+                    this.context.logger.debug(`← ${method} ${url} 200 (${duration}ms)`);
                     return;
                 }
                 // React SPA
                 if (req.method === 'GET' && this.uiConfig && req.url?.startsWith(this.uiConfig.base)) {
                     serveSpa(this.uiConfig, req, res, this.context);
+                    const duration = Date.now() - startTime;
+                    this.context.logger.debug(`← ${method} ${url} ${res.statusCode || 200} (${duration}ms)`);
                     return;
                 }
                 // API routes
@@ -502,6 +536,8 @@ class BuiltPlugin {
                             method,
                             hint: `Available routes: ${this.router.map(r => `${r.method} ${r.name}`).join(', ')}`
                         }));
+                        const duration = Date.now() - startTime;
+                        this.context.logger.debug(`← ${method} ${pathname} 404 (${duration}ms)`);
                         return;
                     }
                     const body = await readBody(req);
@@ -527,16 +563,16 @@ class BuiltPlugin {
                         http: this.context.http
                     };
                     try {
-                        this.context.logger.debug(`📥 ${method} ${pathname}`, { params, body });
                         const result = await route.handler(request, response, routeContext);
                         if (!res.headersSent) {
                             res.writeHead(200, corsHeaders({ 'Content-Type': 'application/json' }));
                             res.end(JSON.stringify(result ?? { success: true }));
                         }
-                        this.context.logger.debug(`📤 ${method} ${pathname} - Success`);
+                        const duration = Date.now() - startTime;
+                        this.context.logger.debug(`← ${method} ${pathname} ${res.statusCode || 200} (${duration}ms)`);
                     }
                     catch (error) {
-                        this.context.logger.error(`❌ ${method} ${pathname} - Error: ${error.message}`);
+                        this.context.logger.error(`API route error: ${method} ${pathname} - ${error.message}`);
                         if (error.stack) {
                             this.context.logger.error(error.stack);
                         }
@@ -548,6 +584,8 @@ class BuiltPlugin {
                                 path: pathname
                             }));
                         }
+                        const duration = Date.now() - startTime;
+                        this.context.logger.debug(`← ${method} ${pathname} 500 (${duration}ms)`);
                     }
                     return;
                 }
@@ -601,6 +639,7 @@ function definePlugin(id, name, version) {
     let _settings = null;
     let _onReady = null;
     let _healthCheck = null;
+    let _pluginRoot = undefined;
     const builder = {
         topbar(route, opts) {
             _topbars.push({
@@ -718,6 +757,13 @@ function definePlugin(id, name, version) {
             _healthCheck = fn;
             return this;
         },
+        pluginRoot(dir) {
+            if (!dir || typeof dir !== 'string') {
+                throw new PluginBuildError('pluginRoot must be a non-empty string', 'Pass __dirname from your plugin entry file: .pluginRoot(__dirname)', { provided: dir });
+            }
+            _pluginRoot = dir;
+            return this;
+        },
         build() {
             // ========== Build-Time Validation ==========
             // Validate React UI setup
@@ -811,7 +857,7 @@ function definePlugin(id, name, version) {
             // Return a class that instantiates BuiltPlugin
             return class extends BuiltPlugin {
                 constructor() {
-                    super(id, name, version, _capabilities, _tools, _apiRoutes, _uiConfigured ? _ui : null, _reactScreens, _htmlScreens, _wizard, _onReady, _healthCheck);
+                    super(id, name, version, _capabilities, _tools, _apiRoutes, _uiConfigured ? _ui : null, _reactScreens, _htmlScreens, _wizard, _onReady, _healthCheck, _pluginRoot);
                 }
             };
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@majkapp/plugin-kit",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Fluent builder framework for creating robust MAJK plugins",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",