@portel/photon-core 2.2.0 → 2.4.0

package/src/asset-discovery.ts

@@ -0,0 +1,160 @@
+/**
+ * Asset Discovery Utilities
+ *
+ * Discover and extract UI, prompt, and resource assets from Photon files.
+ * Extracted from photon's loader.ts.
+ *
+ * Depends on: getMimeType (from ./mime-types), SchemaExtractor (from ./schema-extractor)
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { getMimeType } from './mime-types.js';
+import { SchemaExtractor } from './schema-extractor.js';
+import type { PhotonAssets } from './types.js';
+
+/**
+ * Check if a file or directory exists
+ */
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Discover and extract assets from a Photon file
+ *
+ * Convention:
+ * - Asset folder: {photon-name}/ next to {photon-name}.photon.ts
+ * - Subfolder: ui/, prompts/, resources/
+ *
+ * @param photonPath - Absolute path to the .photon.ts file
+ * @param source - Source code content of the Photon file
+ */
+export async function discoverAssets(
+  photonPath: string,
+  source: string,
+): Promise<PhotonAssets | undefined> {
+  const extractor = new SchemaExtractor();
+  const dir = path.dirname(photonPath);
+  const basename = path.basename(photonPath, '.photon.ts');
+
+  // Convention: asset folder has same name as photon (without .photon.ts)
+  const assetFolder = path.join(dir, basename);
+
+  // Check if asset folder exists
+  let folderExists = false;
+  try {
+    const stat = await fs.stat(assetFolder);
+    folderExists = stat.isDirectory();
+  } catch {
+    // Folder doesn't exist
+  }
+
+  // Extract explicit asset declarations from source annotations
+  const assets = extractor.extractAssets(source, folderExists ? assetFolder : undefined);
+
+  // If no folder exists and no explicit declarations, skip
+  if (
+    !folderExists &&
+    assets.ui.length === 0 &&
+    assets.prompts.length === 0 &&
+    assets.resources.length === 0
+  ) {
+    return undefined;
+  }
+
+  if (folderExists) {
+    // Resolve paths for explicitly declared assets
+    for (const ui of assets.ui) {
+      ui.resolvedPath = path.resolve(assetFolder, ui.path.replace(/^\.\//, ''));
+    }
+    for (const prompt of assets.prompts) {
+      prompt.resolvedPath = path.resolve(assetFolder, prompt.path.replace(/^\.\//, ''));
+    }
+    for (const resource of assets.resources) {
+      resource.resolvedPath = path.resolve(assetFolder, resource.path.replace(/^\.\//, ''));
+    }
+
+    // Auto-discover assets from folder structure
+    await autoDiscoverAssets(assetFolder, assets);
+  }
+
+  return assets;
+}
+
+/**
+ * Auto-discover assets from the ui/, prompts/, resources/ subdirectories
+ */
+export async function autoDiscoverAssets(
+  assetFolder: string,
+  assets: PhotonAssets,
+): Promise<void> {
+  // Auto-discover UI files
+  const uiDir = path.join(assetFolder, 'ui');
+  if (await fileExists(uiDir)) {
+    try {
+      const files = await fs.readdir(uiDir);
+      for (const file of files) {
+        const id = path.basename(file, path.extname(file));
+        if (!assets.ui.find((u) => u.id === id)) {
+          assets.ui.push({
+            id,
+            path: `./ui/${file}`,
+            resolvedPath: path.join(uiDir, file),
+            mimeType: getMimeType(file),
+          });
+        }
+      }
+    } catch {
+      // Ignore errors
+    }
+  }
+
+  // Auto-discover prompt files
+  const promptsDir = path.join(assetFolder, 'prompts');
+  if (await fileExists(promptsDir)) {
+    try {
+      const files = await fs.readdir(promptsDir);
+      for (const file of files) {
+        if (file.endsWith('.md') || file.endsWith('.txt')) {
+          const id = path.basename(file, path.extname(file));
+          if (!assets.prompts.find((p) => p.id === id)) {
+            assets.prompts.push({
+              id,
+              path: `./prompts/${file}`,
+              resolvedPath: path.join(promptsDir, file),
+            });
+          }
+        }
+      }
+    } catch {
+      // Ignore errors
+    }
+  }
+
+  // Auto-discover resource files
+  const resourcesDir = path.join(assetFolder, 'resources');
+  if (await fileExists(resourcesDir)) {
+    try {
+      const files = await fs.readdir(resourcesDir);
+      for (const file of files) {
+        const id = path.basename(file, path.extname(file));
+        if (!assets.resources.find((r) => r.id === id)) {
+          assets.resources.push({
+            id,
+            path: `./resources/${file}`,
+            resolvedPath: path.join(resourcesDir, file),
+            mimeType: getMimeType(file),
+          });
+        }
+      }
+    } catch {
+      // Ignore errors
+    }
+  }
+}

package/src/base.ts

@@ -125,22 +125,29 @@ export class PhotonMCP {
 
   /**
    * Get all tool methods from this class
-   * Returns all public async methods except lifecycle hooks
+   * Returns all public async methods except lifecycle hooks and configuration methods
    */
   static getToolMethods(): string[] {
     const prototype = this.prototype;
     const methods: string[] = [];
 
+    // Methods that are conventions, not tools
+    const conventionMethods = new Set([
+      'constructor',
+      'onInitialize',  // Lifecycle hook
+      'onShutdown',    // Lifecycle hook
+      'configure',     // Configuration convention
+      'getConfig',     // Configuration convention
+    ]);
+
     // 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
+        // Skip private methods (starting with _) and convention methods
         if (
-          name !== 'constructor' &&
           !name.startsWith('_') &&
-          name !== 'onInitialize' &&
-          name !== 'onShutdown' &&
+          !conventionMethods.has(name) &&
           typeof (prototype as any)[name] === 'function' &&
           !methods.includes(name)
         ) {

package/src/class-detection.ts

@@ -0,0 +1,94 @@
+/**
+ * Class Detection Utilities
+ *
+ * Shared logic for detecting Photon classes in ES modules.
+ * Extracted from photon, ncp, and lumina loaders.
+ */
+
+/**
+ * Check if a value is a class constructor
+ */
+export function isClass(fn: unknown): fn is new (...args: unknown[]) => unknown {
+  return typeof fn === 'function' && /^\s*class\s+/.test(fn.toString());
+}
+
+/**
+ * Check if a class has async methods (instance or static)
+ *
+ * Checks for AsyncFunction, AsyncGeneratorFunction, and GeneratorFunction
+ * on both prototype (instance methods) and the class itself (static methods).
+ */
+export function hasAsyncMethods(ClassConstructor: new (...args: unknown[]) => unknown): boolean {
+  const asyncCtorNames = new Set([
+    'AsyncFunction',
+    'AsyncGeneratorFunction',
+    'GeneratorFunction',
+  ]);
+
+  // Check instance methods on prototype
+  const prototype = ClassConstructor.prototype;
+  for (const key of Object.getOwnPropertyNames(prototype)) {
+    if (key === 'constructor') continue;
+    const descriptor = Object.getOwnPropertyDescriptor(prototype, key);
+    if (descriptor && typeof descriptor.value === 'function') {
+      if (asyncCtorNames.has(descriptor.value.constructor.name)) {
+        return true;
+      }
+    }
+  }
+
+  // Check static methods on the class itself
+  for (const key of Object.getOwnPropertyNames(ClassConstructor)) {
+    if (['length', 'name', 'prototype'].includes(key)) continue;
+    const descriptor = Object.getOwnPropertyDescriptor(ClassConstructor, key);
+    if (descriptor && typeof descriptor.value === 'function') {
+      if (asyncCtorNames.has(descriptor.value.constructor.name)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Find a single Photon class in a module
+ *
+ * Priority: default export first, then named exports.
+ * Returns the first class with async methods, or null.
+ */
+export function findPhotonClass(module: Record<string, unknown>): (new (...args: unknown[]) => unknown) | null {
+  // Try default export first
+  if (module.default && isClass(module.default)) {
+    if (hasAsyncMethods(module.default)) {
+      return module.default;
+    }
+  }
+
+  // Try named exports
+  for (const exportedItem of Object.values(module)) {
+    if (isClass(exportedItem) && hasAsyncMethods(exportedItem)) {
+      return exportedItem;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Find all Photon classes in a module
+ *
+ * Returns every exported class that has async methods.
+ * Used by NCP which may load multiple classes from one file.
+ */
+export function findPhotonClasses(module: Record<string, unknown>): Array<new (...args: unknown[]) => unknown> {
+  const classes: Array<new (...args: unknown[]) => unknown> = [];
+
+  for (const exportedItem of Object.values(module)) {
+    if (isClass(exportedItem) && hasAsyncMethods(exportedItem)) {
+      classes.push(exportedItem);
+    }
+  }
+
+  return classes;
+}

package/src/compiler.ts

@@ -0,0 +1,57 @@
+/**
+ * TypeScript Compiler Utilities
+ *
+ * Shared esbuild-based TypeScript compilation with caching.
+ * Extracted from photon and ncp loaders.
+ *
+ * NOTE: No esbuild dependency in package.json — the consumer must provide it.
+ * Uses `await import('esbuild')` for dynamic resolution.
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as crypto from 'crypto';
+
+/**
+ * Compile a .photon.ts file to JavaScript and cache the result
+ *
+ * @param tsFilePath - Absolute path to the TypeScript source file
+ * @param options.cacheDir - Directory to store compiled output
+ * @param options.content - Optional pre-read file content (avoids extra read)
+ * @returns Absolute path to the compiled .mjs file
+ */
+export async function compilePhotonTS(
+  tsFilePath: string,
+  options: { cacheDir: string; content?: string },
+): Promise<string> {
+  const source = options.content ?? (await fs.readFile(tsFilePath, 'utf-8'));
+  const hash = crypto.createHash('sha256').update(source).digest('hex').slice(0, 16);
+
+  const fileName = path.basename(tsFilePath, '.ts');
+  const cachedJsPath = path.join(options.cacheDir, `${fileName}.${hash}.mjs`);
+
+  // Check if cached version exists
+  try {
+    await fs.access(cachedJsPath);
+    return cachedJsPath;
+  } catch {
+    // Cache miss — compile
+  }
+
+  // Dynamic import — consumer must have esbuild installed
+  const esbuild = await import('esbuild');
+  const result = await esbuild.transform(source, {
+    loader: 'ts',
+    format: 'esm',
+    target: 'es2022',
+    sourcemap: 'inline',
+  });
+
+  // Ensure cache directory exists
+  await fs.mkdir(options.cacheDir, { recursive: true });
+
+  // Write compiled JavaScript
+  await fs.writeFile(cachedJsPath, result.code, 'utf-8');
+
+  return cachedJsPath;
+}

package/src/config.ts

@@ -0,0 +1,134 @@
+/**
+ * Photon Configuration Utilities
+ *
+ * Provides standard config storage for photons that implement the configure() convention.
+ * Config is stored at ~/.photon/{photonName}/config.json
+ *
+ * Usage in a Photon:
+ * ```typescript
+ * import { loadPhotonConfig, savePhotonConfig, getPhotonConfigPath } from '@portel/photon-core';
+ *
+ * export default class MyPhoton extends PhotonMCP {
+ *   async configure(params: { apiKey: string }) {
+ *     savePhotonConfig('my-photon', params);
+ *     return { success: true, config: params };
+ *   }
+ *
+ *   async getConfig() {
+ *     return loadPhotonConfig('my-photon');
+ *   }
+ * }
+ * ```
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+/**
+ * Get the config directory for photons
+ * Default: ~/.photon/
+ */
+export function getPhotonConfigDir(): string {
+  return process.env.PHOTON_CONFIG_DIR || path.join(os.homedir(), '.photon');
+}
+
+/**
+ * Get the config file path for a specific photon
+ * @param photonName The photon name (kebab-case)
+ * @returns Path to config.json for this photon
+ */
+export function getPhotonConfigPath(photonName: string): string {
+  const safeName = photonName.replace(/[^a-zA-Z0-9_-]/g, '_');
+  return path.join(getPhotonConfigDir(), safeName, 'config.json');
+}
+
+/**
+ * Load configuration for a photon
+ * @param photonName The photon name (kebab-case)
+ * @param defaults Default values if config doesn't exist
+ * @returns The config object or defaults
+ */
+export function loadPhotonConfig<T extends Record<string, any>>(
+  photonName: string,
+  defaults?: T
+): T {
+  const configPath = getPhotonConfigPath(photonName);
+
+  try {
+    if (fs.existsSync(configPath)) {
+      const content = fs.readFileSync(configPath, 'utf-8');
+      const config = JSON.parse(content);
+      // Merge with defaults
+      return defaults ? { ...defaults, ...config } : config;
+    }
+  } catch (error) {
+    // Log but don't throw - return defaults
+    if (process.env.PHOTON_DEBUG) {
+      console.error(`Failed to load config for ${photonName}:`, error);
+    }
+  }
+
+  return defaults || ({} as T);
+}
+
+/**
+ * Save configuration for a photon
+ * @param photonName The photon name (kebab-case)
+ * @param config The configuration object to save
+ */
+export function savePhotonConfig<T extends Record<string, any>>(
+  photonName: string,
+  config: T
+): void {
+  const configPath = getPhotonConfigPath(photonName);
+  const configDir = path.dirname(configPath);
+
+  // Ensure directory exists
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true });
+  }
+
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+}
+
+/**
+ * Check if a photon has been configured
+ * @param photonName The photon name (kebab-case)
+ * @returns true if config file exists
+ */
+export function hasPhotonConfig(photonName: string): boolean {
+  return fs.existsSync(getPhotonConfigPath(photonName));
+}
+
+/**
+ * Delete configuration for a photon
+ * @param photonName The photon name (kebab-case)
+ */
+export function deletePhotonConfig(photonName: string): void {
+  const configPath = getPhotonConfigPath(photonName);
+  if (fs.existsSync(configPath)) {
+    fs.unlinkSync(configPath);
+  }
+}
+
+/**
+ * List all configured photons
+ * @returns Array of photon names that have config
+ */
+export function listConfiguredPhotons(): string[] {
+  const configDir = getPhotonConfigDir();
+
+  if (!fs.existsSync(configDir)) {
+    return [];
+  }
+
+  try {
+    return fs.readdirSync(configDir, { withFileTypes: true })
+      .filter(entry => entry.isDirectory())
+      .filter(entry => fs.existsSync(path.join(configDir, entry.name, 'config.json')))
+      .map(entry => entry.name);
+  } catch {
+    return [];
+  }
+}