@workopilot/pluginapi-dev-host 0.1.0

package/README.md

@@ -0,0 +1,134 @@
+# @workopilot/pluginapi-dev-host
+
+Workopilot Plugin API Dev Host is a local development server for third-party plugin projects.
+
+It simulates the Workopilot host application during development: it loads a plugin manifest, imports plugin handlers, injects database access from `.env.local`, parses the JWT payload from `Authorization: Bearer <token>`, injects `ctx.currentUser`, and exposes plugin routes locally.
+
+It is intended for local development only. Production plugin loading, JWT signature verification, Redis token validation, and plugin package installation are handled by the real host application.
+
+## Installation
+
+```bash
+npm install --save-dev @workopilot/pluginapi-dev-host
+```
+
+Plugin projects should also install the SDK:
+
+```bash
+npm install @workopilot/pluginapi-sdk
+```
+
+## Usage
+
+Add a development script in the plugin project's `package.json`:
+
+```json
+{
+  "scripts": {
+    "dev": "npm run build && plugin-dev-host --plugin . --env .env.local --port 3100"
+  }
+}
+```
+
+Start local development:
+
+```bash
+npm run dev
+```
+
+Then request plugin routes through the local dev host:
+
+```bash
+curl -H "Authorization: Bearer <jwt-token>" http://127.0.0.1:3100/plugins/my-plugin/me
+```
+
+The plugin name comes from `plugin.json`:
+
+```json
+{
+  "name": "my-plugin",
+  "entry": "dist/index.js",
+  "routes": [
+    {
+      "method": "GET",
+      "path": "/me",
+      "handler": "getCurrentUser"
+    }
+  ]
+}
+```
+
+The final route format is:
+
+```text
+/plugins/<plugin-name>/<route-path>
+```
+
+## Configuration
+
+The dev host requires a database env file. By default, pass `.env.local`:
+
+```bash
+plugin-dev-host --plugin . --env .env.local --port 3100
+```
+
+Example `.env.local`:
+
+```env
+DB_HOST=127.0.0.1
+DB_NAME=plugin_dev
+DB_USER=root
+DB_PASSWORD=password
+DB_PORT=3306
+DB_SSL=false
+DB_CHARSET=utf8
+```
+
+If the env file cannot be found, the dev host fails to start. It does not include default database credentials.
+
+## Provided Capabilities
+
+### Database
+
+The dev host injects:
+
+```ts
+ctx.database.query(sql, params)
+ctx.database.insert(sql, params)
+ctx.database.update(sql, params)
+ctx.database.delete(sql, params)
+```
+
+### Current User
+
+Every plugin route request must include:
+
+```text
+Authorization: Bearer <jwt-token>
+```
+
+For local development, the dev host only parses the JWT payload and maps it to:
+
+```ts
+ctx.currentUser
+```
+
+It does not verify the JWT signature, does not check Redis, and does not validate token lifetime.
+
+### Logger
+
+The dev host injects:
+
+```ts
+ctx.logger.info(message, data)
+ctx.logger.error(message, data)
+```
+
+## CLI Options
+
+```text
+--plugin  Plugin project directory. Default: .
+--env     Database env file. Default: .env.local
+--host    Listen host. Default: 127.0.0.1
+--port    Listen port. Default: 3100
+```

package/dist/auth.d.ts

@@ -0,0 +1,6 @@
+import type { FastifyRequest } from 'fastify';
+import type { CurrentUser } from '@workopilot/pluginapi-sdk';
+export declare class DevAuthError extends Error {
+    constructor(message: string);
+}
+export declare function authenticateDevRequest(request: FastifyRequest): CurrentUser;

package/dist/auth.js

@@ -0,0 +1,65 @@
+export class DevAuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DevAuthError';
+    }
+}
+export function authenticateDevRequest(request) {
+    const token = readBearerToken(request.headers.authorization);
+    const payload = parseJwtPayload(token);
+    return toCurrentUser(payload);
+}
+function readBearerToken(authorization) {
+    const value = Array.isArray(authorization) ? authorization[0] : authorization;
+    if (!value) {
+        throw new DevAuthError('Missing Authorization header.');
+    }
+    const match = /^Bearer\s+(.+)$/i.exec(value.trim());
+    if (!match) {
+        throw new DevAuthError('Authorization header must use Bearer token.');
+    }
+    return match[1];
+}
+function parseJwtPayload(token) {
+    const parts = token.split('.');
+    if (parts.length < 2) {
+        throw new DevAuthError('Invalid JWT format.');
+    }
+    try {
+        return JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+    }
+    catch {
+        throw new DevAuthError('Invalid JWT payload.');
+    }
+}
+function toCurrentUser(payload) {
+    const loginId = readRequiredString(payload.loginId, 'loginId');
+    const userId = loginId.split(':').at(-1);
+    if (!userId) {
+        throw new DevAuthError('JWT loginId does not contain a user id.');
+    }
+    return {
+        tenantId: readRequiredString(payload.tenantId, 'tenantId'),
+        userId,
+        clientid: readRequiredString(payload.clientid, 'clientid'),
+        userName: readRequiredString(payload.userName, 'userName'),
+        deptId: readOptionalStringOrNumber(payload.deptId),
+        deptName: readOptionalString(payload.deptName),
+        deptCategory: readOptionalString(payload.deptCategory)
+    };
+}
+function readRequiredString(value, fieldName) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new DevAuthError(`JWT payload field "${fieldName}" is required.`);
+    }
+    return value;
+}
+function readOptionalString(value) {
+    return typeof value === 'string' ? value : '';
+}
+function readOptionalStringOrNumber(value) {
+    if (typeof value === 'string' || typeof value === 'number') {
+        return value;
+    }
+    return null;
+}

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+import Fastify from 'fastify';
+import { config as loadEnvFile } from 'dotenv';
+import mysql from 'mysql2/promise';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { DevAuthError, authenticateDevRequest } from './auth.js';
+function readOptions(argv) {
+    const options = {};
+    for (let index = 0; index < argv.length; index += 2) {
+        const key = argv[index];
+        const value = argv[index + 1];
+        if (!key?.startsWith('--') || !value) {
+            throw new Error('Usage: plugin-dev-host --plugin . --env .env.local --port 3100');
+        }
+        options[key.slice(2)] = value;
+    }
+    return {
+        pluginDir: resolve(options.plugin ?? '.'),
+        envFile: resolve(options.env ?? '.env.local'),
+        host: options.host ?? '127.0.0.1',
+        port: Number(options.port ?? 3100)
+    };
+}
+function loadDatabaseEnv(envFile) {
+    if (!existsSync(envFile)) {
+        throw new Error(`Database env file was not found: ${envFile}`);
+    }
+    loadEnvFile({ path: envFile });
+    return { source: envFile };
+}
+function createDatabaseCapability() {
+    const requiredKeys = ['DB_HOST', 'DB_NAME', 'DB_USER', 'DB_PASSWORD'];
+    for (const key of requiredKeys) {
+        if (!process.env[key]) {
+            throw new Error(`Missing required environment variable: ${key}`);
+        }
+    }
+    const pool = mysql.createPool({
+        host: process.env.DB_HOST,
+        database: process.env.DB_NAME,
+        user: process.env.DB_USER,
+        password: process.env.DB_PASSWORD,
+        port: Number(process.env.DB_PORT ?? 3306),
+        charset: process.env.DB_CHARSET ?? 'utf8',
+        ssl: process.env.DB_SSL === 'true' ? {} : undefined,
+        waitForConnections: true,
+        connectionLimit: 5
+    });
+    return {
+        async query(sql, params = []) {
+            const [rows] = await pool.query(sql, params);
+            return rows;
+        },
+        async insert(sql, params = []) {
+            return executeWrite(sql, params);
+        },
+        async update(sql, params = []) {
+            return executeWrite(sql, params);
+        },
+        async delete(sql, params = []) {
+            return executeWrite(sql, params);
+        },
+        async close() {
+            await pool.end();
+        }
+    };
+    async function executeWrite(sql, params) {
+        const [result] = await pool.execute(sql, params);
+        return {
+            affectedRows: result.affectedRows,
+            insertId: result.insertId,
+            warningStatus: result.warningStatus,
+            changedRows: result.changedRows,
+            info: result.info
+        };
+    }
+}
+async function loadManifest(pluginDir) {
+    const content = await readFile(resolve(pluginDir, 'plugin.json'), 'utf8');
+    return JSON.parse(content);
+}
+async function loadHandlers(pluginDir, manifest) {
+    const modulePath = resolve(pluginDir, manifest.entry);
+    const moduleUrl = `${pathToFileURL(modulePath).href}?v=${Date.now()}`;
+    const pluginModule = (await import(moduleUrl));
+    const handlers = {};
+    for (const route of manifest.routes) {
+        const handler = pluginModule[route.handler];
+        if (typeof handler !== 'function') {
+            throw new Error(`Plugin does not export handler "${route.handler}".`);
+        }
+        handlers[route.handler] = handler;
+    }
+    return handlers;
+}
+function normalizePath(path) {
+    if (!path || path === '/') {
+        return '/';
+    }
+    return path.endsWith('/') ? path.slice(0, -1) : path;
+}
+const options = readOptions(process.argv.slice(2));
+const databaseEnv = loadDatabaseEnv(options.envFile);
+const manifest = await loadManifest(options.pluginDir);
+const handlers = await loadHandlers(options.pluginDir, manifest);
+const database = createDatabaseCapability();
+const app = Fastify({
+    logger: true
+});
+app.log.info({ source: databaseEnv.source }, 'plugin dev host database configuration loaded');
+app.addHook('onClose', async () => {
+    await database.close();
+});
+app.get('/health', async () => ({
+    ok: true,
+    service: 'plugin-dev-host',
+    plugin: manifest.name
+}));
+app.all('/plugins/:pluginName/*', async (request, reply) => {
+    try {
+        const currentUser = authenticateDevRequest(request);
+        const params = request.params;
+        if (params.pluginName !== manifest.name) {
+            return reply.code(404).send({ message: `Dev host loaded plugin "${manifest.name}".` });
+        }
+        const pluginPath = `/${params['*'] ?? ''}`;
+        const route = manifest.routes.find((candidate) => candidate.method === request.method && normalizePath(candidate.path) === normalizePath(pluginPath));
+        if (!route) {
+            return reply.code(404).send({ message: `Route ${request.method} /plugins/${manifest.name}${pluginPath} is not registered.` });
+        }
+        const ctx = {
+            database,
+            currentUser,
+            logger: {
+                info: (message, data) => app.log.info({ plugin: manifest.name, data }, message),
+                error: (message, data) => app.log.error({ plugin: manifest.name, data }, message)
+            }
+        };
+        const pluginRequest = {
+            method: request.method,
+            url: request.url,
+            query: request.query,
+            body: request.body,
+            headers: request.headers
+        };
+        const result = await handlers[route.handler]({ request: pluginRequest, ctx });
+        return reply.send(result);
+    }
+    catch (error) {
+        if (error instanceof DevAuthError) {
+            return reply.code(401).send({ message: error.message });
+        }
+        throw error;
+    }
+});
+await app.listen({ host: options.host, port: options.port });

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@workopilot/pluginapi-dev-host",
+  "version": "0.1.0",
+  "description": "Workopilot plugin API local development host",
+  "keywords": [
+    "wiseai",
+    "workopilot",
+    "plugin",
+    "dev-host"
+  ],
+  "author": "workopilot",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "plugin-dev-host": "dist/cli.js"
+  },
+  "main": "dist/cli.js",
+  "types": "dist/cli.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@workopilot/pluginapi-sdk": "0.1.0",
+    "dotenv": "^16.4.7",
+    "fastify": "^5.2.1",
+    "mysql2": "^3.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  }
+}