@portel/photon-core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Portel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,403 @@
+# @portel/photon-core
+
+**Core library for parsing, loading, and managing `.photon.ts` files**
+
+[![npm version](https://badge.fury.io/js/@portel%2Fphoton-core.svg)](https://www.npmjs.com/package/@portel/photon-core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 🎯 What is Photon Core?
+
+Photon Core is the **runtime-agnostic foundation** for working with `.photon.ts` files. It provides:
+
+- ✅ **Base class** with lifecycle hooks (`onInitialize`, `onShutdown`)
+- ✅ **Dependency management** - Extract and install `@dependencies` from JSDoc
+- ✅ **Schema extraction** - Parse TypeScript types and JSDoc into JSON schemas
+- ❌ **NO runtime layers** - No MCP server, no CLI, no transport
+
+This allows you to build **custom runtimes** on top of the Photon format:
+- **Multi-protocol API servers** (REST, GraphQL, RPC, MCP) → [Lumina](https://github.com/portel-dev/lumina)
+- **Orchestrators** → [NCP](https://github.com/portel-dev/ncp)
+- **MCP/CLI runners** → [@portel/photon](https://github.com/portel-dev/photon)
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @portel/photon-core
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Create a Photon class
+
+```typescript
+// calculator.photon.ts
+
+/**
+ * Simple calculator with basic math operations
+ * @dependencies lodash@^4.17.21
+ */
+export default class Calculator {
+  /**
+   * Add two numbers together
+   * @param a First number
+   * @param b Second number
+   */
+  async add(params: { a: number; b: number }) {
+    return params.a + params.b;
+  }
+
+  /**
+   * Multiply two numbers
+   * @param a First number
+   * @param b Second number
+   */
+  async multiply(params: { a: number; b: number }) {
+    return params.a * params.b;
+  }
+
+  /**
+   * Lifecycle hook called when photon is initialized
+   */
+  async onInitialize() {
+    console.log('Calculator initialized!');
+  }
+
+  /**
+   * Lifecycle hook called when photon is shut down
+   */
+  async onShutdown() {
+    console.log('Calculator shutting down!');
+  }
+}
+```
+
+### 2. Use Photon Core to load and manage it
+
+```typescript
+import { PhotonMCP, DependencyManager, SchemaExtractor } from '@portel/photon-core';
+
+// 1. Extract and install dependencies
+const depManager = new DependencyManager();
+const deps = await depManager.extractDependencies('./calculator.photon.ts');
+// Found: [{ name: 'lodash', version: '^4.17.21' }]
+
+await depManager.ensureDependencies('calculator', deps);
+// ✅ Dependencies installed
+
+// 2. Load the class
+const CalculatorClass = (await import('./calculator.photon.ts')).default;
+const instance = new CalculatorClass();
+
+// 3. Call lifecycle hook
+if (instance.onInitialize) {
+  await instance.onInitialize();
+}
+
+// 4. Extract schemas (optional)
+const extractor = new SchemaExtractor();
+const schemas = await extractor.extractFromFile('./calculator.photon.ts');
+console.log(schemas);
+// [
+//   {
+//     name: 'add',
+//     description: 'Add two numbers together',
+//     inputSchema: {
+//       type: 'object',
+//       properties: {
+//         a: { type: 'number', description: 'First number' },
+//         b: { type: 'number', description: 'Second number' }
+//       },
+//       required: ['a', 'b']
+//     }
+//   },
+//   ...
+// ]
+
+// 5. Execute methods
+const result = await instance.add({ a: 5, b: 3 });
+console.log(result); // 8
+
+// 6. Cleanup
+if (instance.onShutdown) {
+  await instance.onShutdown();
+}
+```
+
+---
+
+## 📚 API Reference
+
+### `PhotonMCP`
+
+Base class for creating Photon classes (optional - you can use plain classes too).
+
+```typescript
+import { PhotonMCP } from '@portel/photon-core';
+
+export default class MyPhoton extends PhotonMCP {
+  async myMethod(params: { input: string }) {
+    return `Hello ${params.input}`;
+  }
+
+  async onInitialize() {
+    // Called when photon is loaded
+  }
+
+  async onShutdown() {
+    // Called when photon is unloaded
+  }
+}
+```
+
+**Static methods:**
+- `getMCPName()` - Convert class name to kebab-case (e.g., `MyAwesomeMCP` → `my-awesome-mcp`)
+- `getToolMethods()` - Get all public async methods (excludes lifecycle hooks and private methods)
+
+**Instance methods:**
+- `executeTool(name, params)` - Execute a method by name
+
+**Lifecycle hooks:**
+- `onInitialize()` - Called when photon is initialized
+- `onShutdown()` - Called when photon is shut down
+
+---
+
+### `DependencyManager`
+
+Extracts and installs npm dependencies declared in JSDoc `@dependencies` tags.
+
+```typescript
+import { DependencyManager } from '@portel/photon-core';
+
+const depManager = new DependencyManager();
+
+// Extract dependencies from source file
+const deps = await depManager.extractDependencies('./my-tool.photon.ts');
+// [{ name: 'axios', version: '^1.0.0' }, { name: 'date-fns', version: '^2.0.0' }]
+
+// Install dependencies to isolated cache
+await depManager.ensureDependencies('my-tool', deps);
+// Creates ~/.cache/photon-mcp/dependencies/my-tool/node_modules/
+
+// Clear cache for a specific photon
+await depManager.clearCache('my-tool');
+
+// Clear all caches
+await depManager.clearAllCache();
+```
+
+**Supported JSDoc format:**
+```typescript
+/**
+ * @dependencies axios@^1.0.0, date-fns@^2.0.0
+ * @dependencies @octokit/rest@^19.0.0
+ */
+```
+
+---
+
+### `SchemaExtractor`
+
+Extracts JSON schemas from TypeScript method signatures and JSDoc comments.
+
+```typescript
+import { SchemaExtractor } from '@portel/photon-core';
+
+const extractor = new SchemaExtractor();
+
+// Extract from file
+const schemas = await extractor.extractFromFile('./my-tool.photon.ts');
+
+// Extract from source string
+const source = await fs.readFile('./my-tool.photon.ts', 'utf-8');
+const schemas = extractor.extractFromSource(source);
+
+// Extract constructor parameters
+const constructorParams = extractor.extractConstructorParams(source);
+```
+
+**Schema format:**
+```typescript
+interface ExtractedSchema {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, any>;
+    required?: string[];
+  };
+}
+```
+
+**Supported JSDoc constraints:**
+```typescript
+/**
+ * @param age User age {@min 0} {@max 120}
+ * @param email Email address {@format email}
+ * @param username Username {@pattern ^[a-z0-9_]+$}
+ * @param count Count {@default 10}
+ */
+```
+
+---
+
+## 🏗️ Building Custom Runtimes
+
+Photon Core is designed to be the foundation for custom runtimes. Here are examples:
+
+### Example 1: REST API Server
+
+```typescript
+import express from 'express';
+import { PhotonMCP, DependencyManager, SchemaExtractor } from '@portel/photon-core';
+
+class PhotonRESTServer {
+  async serve(photonPath: string) {
+    const app = express();
+
+    // Load photon
+    const PhotonClass = (await import(photonPath)).default;
+    const instance = new PhotonClass();
+    await instance.onInitialize?.();
+
+    // Extract schemas
+    const extractor = new SchemaExtractor();
+    const schemas = await extractor.extractFromFile(photonPath);
+
+    // Create REST endpoints
+    schemas.forEach(schema => {
+      app.post(`/api/${schema.name}`, async (req, res) => {
+        try {
+          const result = await instance[schema.name](req.body);
+          res.json({ result });
+        } catch (error) {
+          res.status(500).json({ error: error.message });
+        }
+      });
+    });
+
+    app.listen(3000);
+  }
+}
+```
+
+### Example 2: GraphQL Server
+
+```typescript
+import { buildSchema } from 'graphql';
+import { PhotonMCP, SchemaExtractor } from '@portel/photon-core';
+
+class PhotonGraphQLServer {
+  async generateSchema(photonPath: string) {
+    const extractor = new SchemaExtractor();
+    const schemas = await extractor.extractFromFile(photonPath);
+
+    const mutations = schemas.map(s =>
+      `${s.name}(${this.paramsToGraphQL(s.inputSchema)}): JSON`
+    ).join('\n');
+
+    return buildSchema(`
+      type Mutation {
+        ${mutations}
+      }
+    `);
+  }
+}
+```
+
+### Example 3: MCP Orchestrator
+
+```typescript
+import { PhotonMCP, DependencyManager } from '@portel/photon-core';
+
+class PhotonOrchestrator {
+  private photons = new Map();
+
+  async loadPhoton(path: string) {
+    // Install dependencies
+    const depManager = new DependencyManager();
+    const deps = await depManager.extractDependencies(path);
+    const name = basename(path, '.photon.ts');
+    await depManager.ensureDependencies(name, deps);
+
+    // Load class
+    const PhotonClass = (await import(path)).default;
+    const instance = new PhotonClass();
+    await instance.onInitialize?.();
+
+    this.photons.set(name, instance);
+  }
+
+  async execute(photonName: string, method: string, params: any) {
+    const photon = this.photons.get(photonName);
+    return await photon[method](params);
+  }
+}
+```
+
+---
+
+## 🎯 Use Cases
+
+| Project | Description | Runtime Layer |
+|---------|-------------|---------------|
+| **[@portel/photon](https://github.com/portel-dev/photon)** | CLI tool for running Photons as MCP servers or CLI tools | MCP server (stdio), CLI runner |
+| **[NCP](https://github.com/portel-dev/ncp)** | Multi-MCP orchestrator with discovery and semantic search | Orchestrator, unified MCP interface |
+| **[Lumina](https://github.com/portel-dev/lumina)** | Multi-protocol API server | REST, GraphQL, RPC, HTTP streaming MCP |
+
+All three projects use `@portel/photon-core` for the shared format, but each adds its own runtime layer.
+
+---
+
+## 🔧 Development
+
+```bash
+# Clone the repository
+git clone https://github.com/portel-dev/photon-core.git
+cd photon-core
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Test
+npm test
+
+# Lint
+npm run lint
+```
+
+---
+
+## 📄 License
+
+MIT © [Portel](https://github.com/portel-dev)
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+---
+
+## 🔗 Related Projects
+
+- **[@portel/photon](https://github.com/portel-dev/photon)** - CLI tool for running Photons
+- **[NCP](https://github.com/portel-dev/ncp)** - Multi-MCP orchestrator
+- **[Lumina](https://github.com/portel-dev/lumina)** - Multi-protocol API server
+
+---
+
+## 📖 Documentation
+
+For more information about the Photon format and ecosystem:
+- [Photon Documentation](https://github.com/portel-dev/photon)
+- [NCP Documentation](https://github.com/portel-dev/ncp)
+- [Lumina Documentation](https://github.com/portel-dev/lumina)

package/dist/base.d.ts

@@ -0,0 +1,58 @@
+/**
+ * PhotonMCP Base Class
+ *
+ * Optional base class for creating Photon MCPs.
+ * You don't need to extend this - any class with async methods works!
+ *
+ * Usage:
+ * ```typescript
+ * export default class Calculator extends PhotonMCP {
+ *   /**
+ *    * Add two numbers together
+ *    * @param a First number
+ *    * @param b Second number
+ *    *\/
+ *   async add(params: { a: number; b: number }) {
+ *     return params.a + params.b;
+ *   }
+ * }
+ * ```
+ *
+ * Or without extending (plain class):
+ * ```typescript
+ * export default class Calculator {
+ *   async add(params: { a: number; b: number }) {
+ *     return params.a + params.b;
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Simple base class for creating Photon MCPs
+ *
+ * - Class name = MCP name
+ * - Public async methods = Tools
+ * - Return value = Tool result
+ */
+export declare class PhotonMCP {
+    /**
+     * Get MCP name from class name
+     * Converts PascalCase to kebab-case (e.g., MyAwesomeMCP → my-awesome-mcp)
+     */
+    static getMCPName(): string;
+    /**
+     * Get all tool methods from this class
+     * Returns all public async methods except lifecycle hooks
+     */
+    static getToolMethods(): string[];
+    /**
+     * Execute a tool method
+     */
+    executeTool(toolName: string, parameters: any): Promise<any>;
+    /**
+     * Optional lifecycle hooks
+     */
+    onInitialize?(): Promise<void>;
+    onShutdown?(): Promise<void>;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;;GAMG;AACH,qBAAa,SAAS;IACpB;;;OAGG;IACH,MAAM,CAAC,UAAU,IAAI,MAAM;IAQ3B;;;OAGG;IACH,MAAM,CAAC,cAAc,IAAI,MAAM,EAAE;IA0BjC;;OAEG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IAgBlE;;OAEG;IACG,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAC9B,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;CACnC"}

package/dist/base.js

@@ -0,0 +1,92 @@
+/**
+ * PhotonMCP Base Class
+ *
+ * Optional base class for creating Photon MCPs.
+ * You don't need to extend this - any class with async methods works!
+ *
+ * Usage:
+ * ```typescript
+ * export default class Calculator extends PhotonMCP {
+ *   /**
+ *    * Add two numbers together
+ *    * @param a First number
+ *    * @param b Second number
+ *    *\/
+ *   async add(params: { a: number; b: number }) {
+ *     return params.a + params.b;
+ *   }
+ * }
+ * ```
+ *
+ * Or without extending (plain class):
+ * ```typescript
+ * export default class Calculator {
+ *   async add(params: { a: number; b: number }) {
+ *     return params.a + params.b;
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Simple base class for creating Photon MCPs
+ *
+ * - Class name = MCP name
+ * - Public async methods = Tools
+ * - Return value = Tool result
+ */
+export class PhotonMCP {
+    /**
+     * Get MCP name from class name
+     * Converts PascalCase to kebab-case (e.g., MyAwesomeMCP → my-awesome-mcp)
+     */
+    static getMCPName() {
+        return this.name
+            .replace(/MCP$/, '') // Remove "MCP" suffix if present
+            .replace(/([A-Z])/g, '-$1')
+            .toLowerCase()
+            .replace(/^-/, ''); // Remove leading dash
+    }
+    /**
+     * Get all tool methods from this class
+     * Returns all public async methods except lifecycle hooks
+     */
+    static getToolMethods() {
+        const prototype = this.prototype;
+        const methods = [];
+        // Get all property names from prototype chain
+        let current = prototype;
+        while (current && current !== PhotonMCP.prototype) {
+            Object.getOwnPropertyNames(current).forEach((name) => {
+                // Skip constructor, private methods (starting with _), and lifecycle hooks
+                if (name !== 'constructor' &&
+                    !name.startsWith('_') &&
+                    name !== 'onInitialize' &&
+                    name !== 'onShutdown' &&
+                    typeof prototype[name] === 'function' &&
+                    !methods.includes(name)) {
+                    methods.push(name);
+                }
+            });
+            current = Object.getPrototypeOf(current);
+        }
+        return methods;
+    }
+    /**
+     * Execute a tool method
+     */
+    async executeTool(toolName, parameters) {
+        const method = this[toolName];
+        if (!method || typeof method !== 'function') {
+            throw new Error(`Tool not found: ${toolName}`);
+        }
+        try {
+            const result = await method.call(this, parameters);
+            return result;
+        }
+        catch (error) {
+            console.error(`Tool execution failed: ${toolName} - ${error.message}`);
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;;GAMG;AACH,MAAM,OAAO,SAAS;IACpB;;;OAGG;IACH,MAAM,CAAC,UAAU;QACf,OAAO,IAAI,CAAC,IAAI;aACb,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,iCAAiC;aACrD,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC;aAC1B,WAAW,EAAE;aACb,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,sBAAsB;IAC9C,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,cAAc;QACnB,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QACjC,MAAM,OAAO,GAAa,EAAE,CAAC;QAE7B,8CAA8C;QAC9C,IAAI,OAAO,GAAG,SAAS,CAAC;QACxB,OAAO,OAAO,IAAI,OAAO,KAAK,SAAS,CAAC,SAAS,EAAE,CAAC;YAClD,MAAM,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;gBACnD,2EAA2E;gBAC3E,IACE,IAAI,KAAK,aAAa;oBACtB,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;oBACrB,IAAI,KAAK,cAAc;oBACvB,IAAI,KAAK,YAAY;oBACrB,OAAQ,SAAiB,CAAC,IAAI,CAAC,KAAK,UAAU;oBAC9C,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,EACvB,CAAC;oBACD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACrB,CAAC;YACH,CAAC,CAAC,CAAC;YACH,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QAC3C,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,WAAW,CAAC,QAAgB,EAAE,UAAe;QACjD,MAAM,MAAM,GAAI,IAAY,CAAC,QAAQ,CAAC,CAAC;QAEvC,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CAAC,mBAAmB,QAAQ,EAAE,CAAC,CAAC;QACjD,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;YACnD,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,OAAO,CAAC,KAAK,CAAC,0BAA0B,QAAQ,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YACvE,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CAOF"}

package/dist/dependency-manager.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Dependency Manager for Photon MCPs
+ *
+ * Handles automatic installation of dependencies declared in MCP files
+ * Similar to Python's UV or npx behavior
+ */
+interface DependencySpec {
+    name: string;
+    version: string;
+}
+/**
+ * Manages dependencies for Photon MCPs
+ */
+export declare class DependencyManager {
+    private cacheDir;
+    constructor();
+    /**
+     * Extract dependencies from MCP source file
+     *
+     * Looks for @dependencies JSDoc tag:
+     * @dependencies axios@^1.0.0, date-fns@^2.0.0
+     * @dependencies octokit@^3.1.0
+     */
+    extractDependencies(sourceFilePath: string): Promise<DependencySpec[]>;
+    /**
+     * Ensure dependencies are installed for an MCP
+     *
+     * Returns the path to node_modules where dependencies are installed
+     */
+    ensureDependencies(mcpName: string, dependencies: DependencySpec[]): Promise<string | null>;
+    /**
+     * Check if dependencies are already installed
+     */
+    private checkInstalled;
+    /**
+     * Run npm install in a directory
+     */
+    private runNpmInstall;
+    /**
+     * Clear cache for an MCP
+     */
+    clearCache(mcpName: string): Promise<void>;
+    /**
+     * Clear all cached dependencies
+     */
+    clearAllCache(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=dependency-manager.d.ts.map

package/dist/dependency-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-manager.d.ts","sourceRoot":"","sources":["../src/dependency-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAS;;IAOzB;;;;;;OAMG;IACG,mBAAmB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IA0C5E;;;;OAIG;IACG,kBAAkB,CACtB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,cAAc,EAAE,GAC7B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA0CzB;;OAEG;YACW,cAAc;IA2B5B;;OAEG;YACW,aAAa;IAqB3B;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUhD;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;CAQrC"}