@portel/photon-core 2.14.0 → 2.16.0

package/src/photon-loader-lite.ts

@@ -368,7 +368,7 @@ function wrapStatefulMethods(
 
   // Skip framework-injected methods from withPhotonCapabilities
   const frameworkMethods = new Set([
-    'emit', 'call', 'mcp', 'setMCPFactory', 'onInitialize', 'onShutdown',
+    'emit', 'render', 'call', 'mcp', 'setMCPFactory', 'onInitialize', 'onShutdown',
   ]);
 
   // Walk the prototype chain to find all public methods

package/src/schema-extractor.ts

@@ -24,6 +24,13 @@ export interface ExtractedMetadata {
   configSchema?: ConfigSchema;
   /** Notification subscription from @notify-on tag */
   notificationSubscriptions?: NotificationSubscription;
+  /**
+   * MCP OAuth auth requirement (from @auth tag)
+   * - 'required': all methods require authenticated caller
+   * - 'optional': caller populated if token present, anonymous allowed
+   * - string URL: OIDC provider URL (implies required)
+   */
+  auth?: 'required' | 'optional' | string;
 }
 
 /**
@@ -64,6 +71,9 @@ export class SchemaExtractor {
     // Notification subscriptions tracking (from @notify-on tag)
     let notificationSubscriptions: NotificationSubscription | undefined;
 
+    // MCP OAuth auth requirement (from @auth tag)
+    let auth: 'required' | 'optional' | string | undefined;
+
     try {
       // If source doesn't contain a class declaration, wrap it in one
       let sourceToParse = source;
@@ -448,6 +458,12 @@ export class SchemaExtractor {
           const classJsdoc = this.getJSDocComment(node as any, sourceFile);
           const isStatefulClass = /@stateful\b/i.test(classJsdoc);
 
+          // Extract @auth tag for MCP OAuth requirement
+          const authMatch = classJsdoc.match(/@auth(?:\s+(\S+))?/i);
+          if (authMatch) {
+            auth = authMatch[1]?.trim() || 'required';
+          }
+
           // Extract notification subscriptions from @notify-on tag
           notificationSubscriptions = this.extractNotifyOn(classJsdoc);
 
@@ -495,6 +511,11 @@ export class SchemaExtractor {
       result.notificationSubscriptions = notificationSubscriptions;
     }
 
+    // Include auth requirement if detected
+    if (auth) {
+      result.auth = auth;
+    }
+
     return result;
   }
 
@@ -1220,7 +1241,7 @@ export class SchemaExtractor {
   private extractDescription(jsdocContent: string): string {
     // Split by @tags that appear at start of a JSDoc line (after optional * prefix)
     // This avoids matching @tag references inline in description text
-    const beforeTags = jsdocContent.split(/(?:^|\n)\s*\*?\s*@(?:param|example|returns?|throws?|see|since|deprecated|version|author|license|ui|icon|format|stateful|autorun|async|webhook|cron|scheduled|locked|fallback|logged|circuitBreaker|cached|timeout|retryable|throttled|debounced|queued|validate|use|Template|Static|mcp|photon|cli|tags|dependencies|csp|visibility)\b/)[0];
+    const beforeTags = jsdocContent.split(/(?:^|\n)\s*\*?\s*@(?:param|example|returns?|throws?|see|since|deprecated|version|author|license|ui|icon|format|stateful|autorun|async|webhook|cron|scheduled|locked|fallback|logged|circuitBreaker|cached|timeout|retryable|throttled|debounced|queued|validate|use|Template|Static|mcp|photon|cli|tags|dependencies|csp|visibility|auth)\b/)[0];
 
     // Remove leading * from each line and trim
     const lines = beforeTags
@@ -1329,6 +1350,7 @@ export class SchemaExtractor {
         .replace(/\{@pattern\s+[^}]+\}/g, '')
         .replace(/\{@format\s+[^}]+\}/g, '')
         .replace(/\{@choice\s+[^}]+\}/g, '')
+        .replace(/\{@choice-from\s+[^}]+\}/g, '')
         .replace(/\{@field\s+[^}]+\}/g, '')
         .replace(/\{@default\s+[^}]+\}/g, '')
         .replace(/\{@unique(?:Items)?\s*\}/g, '')
@@ -1404,6 +1426,12 @@ export class SchemaExtractor {
         paramConstraints.enum = choices;
       }
 
+      // Extract {@choice-from toolName} or {@choice-from toolName.field}
+      const choiceFromMatch = description.match(/\{@choice-from\s+([^}]+)\}/);
+      if (choiceFromMatch) {
+        paramConstraints.choiceFrom = choiceFromMatch[1].trim();
+      }
+
       // Extract {@field type} - hints for UI form rendering
       const fieldMatch = description.match(/\{@field\s+([a-z]+)\}/);
       if (fieldMatch) {
@@ -1526,7 +1554,7 @@ export class SchemaExtractor {
       }
 
       // Validate no unknown {@...} tags (typos in constraint names)
-      const allKnownTags = ['min', 'max', 'pattern', 'format', 'choice', 'field', 'default', 'unique', 'uniqueItems',
+      const allKnownTags = ['min', 'max', 'pattern', 'format', 'choice', 'choice-from', 'field', 'default', 'unique', 'uniqueItems',
                              'example', 'multipleOf', 'deprecated', 'readOnly', 'writeOnly', 'label', 'placeholder',
                              'hint', 'hidden', 'accept', 'minItems', 'maxItems'];
       const unknownTagRegex = /\{@([\w-]+)\s*(?:\s+[^}]*)?\}/g;
@@ -1715,6 +1743,10 @@ export class SchemaExtractor {
           s.enum = constraints.enum;
         }
       }
+      // Apply dynamic choice provider (x-choiceFrom extension)
+      if (constraints.choiceFrom !== undefined) {
+        s['x-choiceFrom'] = constraints.choiceFrom;
+      }
       // Apply field hint for UI rendering
       if (constraints.field !== undefined) {
         s.field = constraints.field;
@@ -2652,7 +2684,7 @@ export class SchemaExtractor {
         };
       }
 
-      // Check if matches an @photon declaration
+      // Check if matches an @photon declaration (exact match)
       if (photonMap.has(param.name)) {
         return {
           param,
@@ -2661,6 +2693,25 @@ export class SchemaExtractor {
         };
       }
 
+      // Instance-aware DI: if paramName ends with a photon dep name (case-insensitive),
+      // the prefix becomes the instance name.
+      // e.g., personalWhatsapp + @photon whatsapp → instance "personal" of whatsapp
+      //       workWhatsapp + @photon whatsapp → instance "work" of whatsapp
+      for (const [depName, dep] of photonMap) {
+        const lowerParam = param.name.toLowerCase();
+        const lowerDep = depName.toLowerCase();
+        if (lowerParam.endsWith(lowerDep) && lowerParam.length > lowerDep.length) {
+          const prefix = param.name.slice(0, param.name.length - depName.length);
+          // Ensure the prefix is a valid instance name (lowercase the first char)
+          const instanceName = prefix.charAt(0).toLowerCase() + prefix.slice(1);
+          return {
+            param,
+            injectionType: 'photon' as const,
+            photonDependency: { ...dep, instanceName: instanceName || undefined },
+          };
+        }
+      }
+
       // Non-primitive with default on @stateful class → persisted state
       if (isStateful && param.hasDefault) {
         return {
@@ -2826,7 +2877,15 @@ export class SchemaExtractor {
                 // Link UI asset to this method
                 const asset = uiAssets.find(a => a.id === uiId);
                 if (asset) {
-                  asset.linkedTool = methodName;
+                  // First method wins as primary (used for app detection)
+                  if (!asset.linkedTool) {
+                    asset.linkedTool = methodName;
+                  }
+                  // Track all methods that reference this UI
+                  if (!asset.linkedTools) asset.linkedTools = [];
+                  if (!asset.linkedTools.includes(methodName)) {
+                    asset.linkedTools.push(methodName);
+                  }
                 }
               }
             }
@@ -2882,7 +2941,7 @@ export class SchemaExtractor {
 /**
  * Capability types that can be auto-detected from source code
  */
-export type PhotonCapability = 'emit' | 'memory' | 'call' | 'mcp' | 'lock' | 'instanceMeta' | 'allInstances';
+export type PhotonCapability = 'emit' | 'memory' | 'call' | 'mcp' | 'lock' | 'instanceMeta' | 'allInstances' | 'caller';
 
 /**
  * Detect capabilities used by a Photon from its source code.
@@ -2896,11 +2955,13 @@ export type PhotonCapability = 'emit' | 'memory' | 'call' | 'mcp' | 'lock' | 'in
 export function detectCapabilities(source: string): Set<PhotonCapability> {
   const caps = new Set<PhotonCapability>();
   if (/this\.emit\s*\(/.test(source)) caps.add('emit');
+  if (/this\.render\s*\(/.test(source)) caps.add('emit'); // render() needs emit injection
   if (/this\.memory\b/.test(source)) caps.add('memory');
   if (/this\.call\s*\(/.test(source)) caps.add('call');
   if (/this\.mcp\s*\(/.test(source)) caps.add('mcp');
   if (/this\.withLock\s*\(/.test(source)) caps.add('lock');
   if (/this\.instanceMeta\b/.test(source)) caps.add('instanceMeta');
   if (/this\.allInstances\s*\(/.test(source)) caps.add('allInstances');
+  if (/this\.caller\b/.test(source)) caps.add('caller');
   return caps;
 }

package/src/types.ts

@@ -432,8 +432,10 @@ export interface UIAsset {
   resolvedPath?: string;
   /** MIME type (detected from extension) */
   mimeType?: string;
-  /** Tool this UI is linked to (from method @ui annotation) */
+  /** Primary tool this UI is linked to (first method with @ui annotation — used for app detection) */
   linkedTool?: string;
+  /** All tools that reference this UI asset (multiple methods can share one template) */
+  linkedTools?: string[];
   /** MCP resource URI (set by loader, e.g., 'ui://photon-name/main-ui') */
   uri?: string;
 }