@portel/photon-core 1.3.0 → 1.4.0

package/src/schema-extractor.ts

@@ -10,7 +10,7 @@
 
 import * as fs from 'fs/promises';
 import * as ts from 'typescript';
-import { ExtractedSchema, ConstructorParam, TemplateInfo, StaticInfo, OutputFormat, YieldInfo, MCPDependency } from './types.js';
+import { ExtractedSchema, ConstructorParam, TemplateInfo, StaticInfo, OutputFormat, YieldInfo, MCPDependency, PhotonDependency, ResolvedInjection, PhotonAssets, UIAsset, PromptAsset, ResourceAsset } from './types.js';
 
 export interface ExtractedMetadata {
   tools: ExtractedSchema[];
@@ -67,13 +67,13 @@ export class SchemaExtractor {
         const isGenerator = member.asteriskToken !== undefined;
 
         // Extract parameter type information
+        // Extract parameter type (may be undefined for no-arg methods)
         const paramsType = this.getFirstParameterType(member, sourceFile);
-        if (!paramsType) {
-          return; // Skip methods without proper params
-        }
 
-        // Build schema from TypeScript type
-        const { properties, required } = this.buildSchemaFromType(paramsType, sourceFile);
+        // Build schema from TypeScript type (empty for no-arg methods)
+        const { properties, required } = paramsType
+          ? this.buildSchemaFromType(paramsType, sourceFile)
+          : { properties: {}, required: [] };
 
         // Extract descriptions from JSDoc
         const paramDocs = this.extractParamDocs(jsdoc);
@@ -130,6 +130,7 @@ export class SchemaExtractor {
         else {
           const outputFormat = this.extractFormat(jsdoc);
           const yields = isGenerator ? this.extractYieldsFromJSDoc(jsdoc) : undefined;
+          const isStateful = this.hasStatefulTag(jsdoc);
 
           tools.push({
             name: methodName,
@@ -138,6 +139,7 @@ export class SchemaExtractor {
             ...(outputFormat ? { outputFormat } : {}),
             ...(isGenerator ? { isGenerator: true } : {}),
             ...(yields && yields.length > 0 ? { yields } : {}),
+            ...(isStateful ? { isStateful: true } : {}),
           });
         }
       };
@@ -450,6 +452,15 @@ export class SchemaExtractor {
     return null;
   }
 
+  /**
+   * Check if a type is a primitive (string, number, boolean)
+   * Primitives are injected from environment variables
+   */
+  private isPrimitiveType(type: string): boolean {
+    const normalizedType = type.trim().toLowerCase();
+    return ['string', 'number', 'boolean'].includes(normalizedType);
+  }
+
   /**
    * Extract constructor parameters for config injection
    */
@@ -486,6 +497,7 @@ export class SchemaExtractor {
                     isOptional,
                     hasDefault,
                     defaultValue,
+                    isPrimitive: this.isPrimitiveType(type),
                   });
                 }
               });
@@ -808,6 +820,14 @@ export class SchemaExtractor {
     return /@Static/i.test(jsdocContent);
   }
 
+  /**
+   * Check if JSDoc contains @stateful tag
+   * Indicates this method is a stateful workflow that supports checkpoint/resume
+   */
+  private hasStatefulTag(jsdocContent: string): boolean {
+    return /@stateful/i.test(jsdocContent);
+  }
+
   /**
    * Extract URI pattern from @Static tag
    * Example: @Static github://repos/{owner}/{repo}/readme
@@ -946,4 +966,331 @@ export class SchemaExtractor {
     // Default: GitHub shorthand (owner/repo)
     return 'github';
   }
+
+  /**
+   * Extract Photon dependencies from source code
+   * Parses @photon tags in file-level or class-level JSDoc comments
+   *
+   * Format: @photon <name> <source>
+   *
+   * Source formats:
+   * - Marketplace: rss-feed (simple name from marketplace)
+   * - GitHub: portel-dev/photons/rss-feed
+   * - npm package: npm:@portel/rss-feed-photon
+   * - Local path: ./my-photon.photon.ts
+   *
+   * Example:
+   * ```
+   * /**
+   *  * @photon rssFeed rss-feed
+   *  * @photon custom ./my-photon.photon.ts
+   *  *\/
+   * ```
+   */
+  extractPhotonDependencies(source: string): PhotonDependency[] {
+    const dependencies: PhotonDependency[] = [];
+
+    // Match @photon <name> <source> pattern
+    // Source ends at: newline, end of comment (*), or @ (next tag)
+    const photonRegex = /@photon\s+(\w+)\s+([^\s*@\n]+)/g;
+
+    let match;
+    while ((match = photonRegex.exec(source)) !== null) {
+      const [, name, rawSource] = match;
+      const photonSource = rawSource.trim();
+
+      // Determine source type
+      const sourceType = this.classifyPhotonSource(photonSource);
+
+      dependencies.push({
+        name,
+        source: photonSource,
+        sourceType,
+      });
+    }
+
+    return dependencies;
+  }
+
+  /**
+   * Classify Photon source type based on format
+   */
+  private classifyPhotonSource(source: string): 'marketplace' | 'github' | 'npm' | 'local' {
+    // npm package: npm:@scope/package or npm:package
+    if (source.startsWith('npm:')) {
+      return 'npm';
+    }
+
+    // Local path (relative or absolute, or ends with .photon.ts)
+    if (source.startsWith('./') || source.startsWith('../') ||
+        source.startsWith('/') || source.startsWith('~') ||
+        /^[A-Za-z]:[\\/]/.test(source) ||
+        source.endsWith('.photon.ts')) {
+      return 'local';
+    }
+
+    // GitHub: has at least 2 slashes (owner/repo/photon) or 1 slash (owner/repo)
+    if ((source.match(/\//g) || []).length >= 1) {
+      return 'github';
+    }
+
+    // Default: Marketplace (simple name like "rss-feed")
+    return 'marketplace';
+  }
+
+  /**
+   * Resolve all injections for a Photon class
+   * Determines how each constructor parameter should be injected:
+   * - Primitives (string, number, boolean) → env var
+   * - Non-primitives matching @mcp → MCP client
+   * - Non-primitives matching @photon → Photon instance
+   *
+   * @param source The Photon source code
+   * @param mcpName The MCP name (for env var prefixing)
+   */
+  resolveInjections(source: string, mcpName: string): ResolvedInjection[] {
+    const params = this.extractConstructorParams(source);
+    const mcpDeps = this.extractMCPDependencies(source);
+    const photonDeps = this.extractPhotonDependencies(source);
+
+    // Build lookup maps
+    const mcpMap = new Map(mcpDeps.map(d => [d.name, d]));
+    const photonMap = new Map(photonDeps.map(d => [d.name, d]));
+
+    return params.map(param => {
+      // Primitives → env var
+      if (param.isPrimitive) {
+        const envVarName = this.toEnvVarName(mcpName, param.name);
+        return {
+          param,
+          injectionType: 'env' as const,
+          envVarName,
+        };
+      }
+
+      // Check if matches an @mcp declaration
+      if (mcpMap.has(param.name)) {
+        return {
+          param,
+          injectionType: 'mcp' as const,
+          mcpDependency: mcpMap.get(param.name),
+        };
+      }
+
+      // Check if matches an @photon declaration
+      if (photonMap.has(param.name)) {
+        return {
+          param,
+          injectionType: 'photon' as const,
+          photonDependency: photonMap.get(param.name),
+        };
+      }
+
+      // Non-primitive without declaration - treat as env var (will likely fail at runtime)
+      const envVarName = this.toEnvVarName(mcpName, param.name);
+      return {
+        param,
+        injectionType: 'env' as const,
+        envVarName,
+      };
+    });
+  }
+
+  /**
+   * Convert MCP name and parameter name to environment variable name
+   * Example: (filesystem, workdir) → FILESYSTEM_WORKDIR
+   */
+  private toEnvVarName(mcpName: string, paramName: string): string {
+    const mcpPrefix = mcpName.toUpperCase().replace(/-/g, '_');
+    const paramSuffix = paramName
+      .replace(/([A-Z])/g, '_$1')
+      .toUpperCase()
+      .replace(/^_/, '');
+    return `${mcpPrefix}_${paramSuffix}`;
+  }
+
+  // ════════════════════════════════════════════════════════════════════════════
+  // ASSET EXTRACTION - @ui, @prompt, @resource annotations
+  // ════════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Extract all assets from Photon source code
+   * Parses @ui, @prompt, @resource annotations from class-level JSDoc
+   *
+   * Format:
+   * - @ui <id> <path> - UI templates for MCP Apps
+   * - @prompt <id> <path> - Static MCP prompts
+   * - @resource <id> <path> - Static MCP resources
+   *
+   * Example:
+   * ```
+   * /**
+   *  * @ui preferences ./ui/preferences.html
+   *  * @prompt system ./prompts/system.md
+   *  * @resource config ./resources/config.json
+   *  *\/
+   * export default class MyPhoton extends PhotonMCP { ... }
+   * ```
+   */
+  extractAssets(source: string, assetFolder?: string): PhotonAssets {
+    const ui = this.extractUIAssets(source);
+    const prompts = this.extractPromptAssets(source);
+    const resources = this.extractResourceAssets(source);
+
+    // Also extract method-level @ui annotations (links UI to specific tool)
+    this.extractMethodUILinks(source, ui);
+
+    return {
+      ui,
+      prompts,
+      resources,
+      assetFolder,
+    };
+  }
+
+  /**
+   * Extract UI assets from @ui annotations
+   * Format: @ui <id> <path>
+   * Path must start with ./ or / to distinguish from method-level @ui references
+   */
+  private extractUIAssets(source: string): UIAsset[] {
+    const assets: UIAsset[] = [];
+    // Path must start with ./ or / to be a declaration (not a reference)
+    const uiRegex = /@ui\s+(\w[\w-]*)\s+(\.\/[^\s*]+|\/[^\s*]+)/g;
+
+    let match;
+    while ((match = uiRegex.exec(source)) !== null) {
+      const [, id, path] = match;
+      assets.push({
+        id,
+        path,
+        mimeType: this.getMimeTypeFromPath(path),
+      });
+    }
+
+    return assets;
+  }
+
+  /**
+   * Extract prompt assets from @prompt annotations
+   * Format: @prompt <id> <path>
+   * Path must start with ./ or / to be a valid declaration
+   */
+  private extractPromptAssets(source: string): PromptAsset[] {
+    const assets: PromptAsset[] = [];
+    const promptRegex = /@prompt\s+(\w[\w-]*)\s+(\.\/[^\s*]+|\/[^\s*]+)/g;
+
+    let match;
+    while ((match = promptRegex.exec(source)) !== null) {
+      const [, id, path] = match;
+      assets.push({
+        id,
+        path,
+      });
+    }
+
+    return assets;
+  }
+
+  /**
+   * Extract resource assets from @resource annotations
+   * Format: @resource <id> <path>
+   * Path must start with ./ or / to be a valid declaration
+   */
+  private extractResourceAssets(source: string): ResourceAsset[] {
+    const assets: ResourceAsset[] = [];
+    const resourceRegex = /@resource\s+(\w[\w-]*)\s+(\.\/[^\s*]+|\/[^\s*]+)/g;
+
+    let match;
+    while ((match = resourceRegex.exec(source)) !== null) {
+      const [, id, path] = match;
+      assets.push({
+        id,
+        path,
+        mimeType: this.getMimeTypeFromPath(path),
+      });
+    }
+
+    return assets;
+  }
+
+  /**
+   * Extract method-level @ui annotations that link UI to tools
+   * Format: @ui <id> on a method's JSDoc
+   */
+  private extractMethodUILinks(source: string, uiAssets: UIAsset[]): void {
+    try {
+      const sourceFile = ts.createSourceFile(
+        'temp.ts',
+        source,
+        ts.ScriptTarget.Latest,
+        true
+      );
+
+      const visit = (node: ts.Node) => {
+        if (ts.isClassDeclaration(node)) {
+          node.members.forEach((member) => {
+            if (ts.isMethodDeclaration(member) &&
+                member.modifiers?.some(m => m.kind === ts.SyntaxKind.AsyncKeyword)) {
+              const jsdoc = this.getJSDocComment(member, sourceFile);
+              const methodName = member.name.getText(sourceFile);
+
+              // Check for @ui <id> in method JSDoc
+              const uiMatch = jsdoc.match(/@ui\s+(\S+)/);
+              if (uiMatch) {
+                const uiId = uiMatch[1];
+                // Link UI asset to this method
+                const asset = uiAssets.find(a => a.id === uiId);
+                if (asset) {
+                  asset.linkedTool = methodName;
+                }
+              }
+            }
+          });
+        }
+        ts.forEachChild(node, visit);
+      };
+
+      visit(sourceFile);
+    } catch (error: any) {
+      // Silently fail - UI links are optional
+    }
+  }
+
+  /**
+   * Get MIME type from file extension
+   */
+  private getMimeTypeFromPath(path: string): string {
+    const ext = path.toLowerCase().split('.').pop() || '';
+    const mimeTypes: Record<string, string> = {
+      // Web
+      'html': 'text/html',
+      'htm': 'text/html',
+      'css': 'text/css',
+      'js': 'application/javascript',
+      'mjs': 'application/javascript',
+      'jsx': 'text/jsx',
+      'ts': 'text/typescript',
+      'tsx': 'text/tsx',
+      // Data
+      'json': 'application/json',
+      'yaml': 'application/yaml',
+      'yml': 'application/yaml',
+      'xml': 'application/xml',
+      'csv': 'text/csv',
+      // Documents
+      'md': 'text/markdown',
+      'txt': 'text/plain',
+      'pdf': 'application/pdf',
+      // Images
+      'png': 'image/png',
+      'jpg': 'image/jpeg',
+      'jpeg': 'image/jpeg',
+      'gif': 'image/gif',
+      'svg': 'image/svg+xml',
+      'webp': 'image/webp',
+      'ico': 'image/x-icon',
+    };
+    return mimeTypes[ext] || 'application/octet-stream';
+  }
 }