@portel/photon-core 1.0.2 → 1.2.0

package/src/index.ts

@@ -76,3 +76,94 @@ export {
 
 // Types
 export * from './types.js';
+
+// Generator-based tools with ask/emit pattern
+// See generator.ts for comprehensive documentation
+export {
+  // Type guards - check yield direction
+  isAskYield,
+  isEmitYield,
+  getAskType,
+  getEmitType,
+
+  // Generator detection
+  isAsyncGeneratorFunction,
+  isAsyncGenerator,
+
+  // Executor - runs generators to completion
+  executeGenerator,
+
+  // Ask extraction (for REST API schema generation)
+  extractAsks,
+
+  // Built-in providers
+  createPrefilledProvider,
+  NeedsInputError,
+
+  // Utility
+  wrapAsGenerator,
+
+  // Ask yield types (input from user)
+  type AskYield,
+  type AskText,
+  type AskPassword,
+  type AskConfirm,
+  type AskSelect,
+  type AskNumber,
+  type AskFile,
+  type AskDate,
+
+  // Emit yield types (output to user)
+  type EmitYield,
+  type EmitStatus,
+  type EmitProgress,
+  type EmitStream,
+  type EmitLog,
+  type EmitToast,
+  type EmitThinking,
+  type EmitArtifact,
+
+  // Combined type
+  type PhotonYield,
+
+  // Execution config
+  type InputProvider,
+  type OutputHandler,
+  type GeneratorExecutorConfig,
+  type ExtractedAsk,
+
+  // Legacy compatibility (deprecated)
+  isInputYield,
+  isProgressYield,
+  isStreamYield,
+  isLogYield,
+  extractYields,
+  type PromptYield,
+  type ConfirmYield,
+  type SelectYield,
+  type ProgressYield,
+  type StreamYield,
+  type LogYield,
+  type ExtractedYield,
+} from './generator.js';
+
+// Elicit - Cross-platform user input (legacy, prefer generators)
+export {
+  // Simple functions (no imports needed in photon files)
+  prompt,
+  confirm,
+  // Full elicit with options
+  elicit,
+  elicitReadline,
+  elicitNativeDialog,
+  // Handler management (for runtimes)
+  setPromptHandler,
+  getPromptHandler,
+  setElicitHandler,
+  getElicitHandler,
+  // Types
+  type ElicitOptions,
+  type ElicitResult,
+  type ElicitHandler,
+  type PromptHandler,
+} from './elicit.js';

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 } from './types.js';
+import { ExtractedSchema, ConstructorParam, TemplateInfo, StaticInfo, OutputFormat, YieldInfo } from './types.js';
 
 export interface ExtractedMetadata {
   tools: ExtractedSchema[];
@@ -63,6 +63,9 @@ export class SchemaExtractor {
         const methodName = member.name.getText(sourceFile);
         const jsdoc = this.getJSDocComment(member, sourceFile);
 
+        // Check if this is an async generator method (has asterisk token)
+        const isGenerator = member.asteriskToken !== undefined;
+
         // Extract parameter type information
         const paramsType = this.getFirstParameterType(member, sourceFile);
         if (!paramsType) {
@@ -126,11 +129,15 @@ export class SchemaExtractor {
         // Otherwise, it's a regular tool
         else {
           const outputFormat = this.extractFormat(jsdoc);
+          const yields = isGenerator ? this.extractYieldsFromJSDoc(jsdoc) : undefined;
+
           tools.push({
             name: methodName,
             description,
             inputSchema,
             ...(outputFormat ? { outputFormat } : {}),
+            ...(isGenerator ? { isGenerator: true } : {}),
+            ...(yields && yields.length > 0 ? { yields } : {}),
           });
         }
       };
@@ -140,7 +147,7 @@ export class SchemaExtractor {
         // Look for class declarations
         if (ts.isClassDeclaration(node)) {
           node.members.forEach((member) => {
-            // Look for async methods
+            // Look for async methods (including async generators with *)
             if (ts.isMethodDeclaration(member) &&
                 member.modifiers?.some(m => m.kind === ts.SyntaxKind.AsyncKeyword)) {
               processMethod(member);
@@ -846,4 +853,27 @@ export class SchemaExtractor {
     const match = jsdocContent.match(/@mimeType\s+([\w\/\-+.]+)/i);
     return match ? match[1].trim() : undefined;
   }
+
+  /**
+   * Extract yield information from JSDoc for generator methods
+   * Supports @yields tags with id, type, and description
+   * Example: @yields {pairing_code} text Enter the 6-digit code shown on TV
+   */
+  private extractYieldsFromJSDoc(jsdocContent: string): YieldInfo[] {
+    const yields: YieldInfo[] = [];
+    // Match @yields {id} type description
+    const yieldRegex = /@yields?\s+\{(\w+)\}\s+(prompt|confirm|select)\s+(.+)/gi;
+
+    let match;
+    while ((match = yieldRegex.exec(jsdocContent)) !== null) {
+      const [, id, type, description] = match;
+      yields.push({
+        id,
+        type: type.toLowerCase() as 'prompt' | 'confirm' | 'select',
+        prompt: description.trim(),
+      });
+    }
+
+    return yields;
+  }
 }

package/src/types.ts

@@ -23,6 +23,22 @@ export interface PhotonTool {
   outputFormat?: OutputFormat;
 }
 
+/**
+ * Yield information extracted from generator methods
+ * Used for REST API schema generation (yields become optional parameters)
+ */
+export interface YieldInfo {
+  id: string;
+  type: 'prompt' | 'confirm' | 'select';
+  prompt?: string;
+  options?: Array<string | { value: string; label: string }>;
+  default?: string;
+  required?: boolean;
+  pattern?: string;
+  dangerous?: boolean;
+  multi?: boolean;
+}
+
 export interface ExtractedSchema {
   name: string;
   description: string;
@@ -32,6 +48,10 @@ export interface ExtractedSchema {
     required?: string[];
   };
   outputFormat?: OutputFormat;
+  /** True if this method is an async generator (uses yield for prompts) */
+  isGenerator?: boolean;
+  /** Yield information for generator methods (used by REST APIs) */
+  yields?: YieldInfo[];
 }
 
 export interface PhotonMCPClass {