@portel/photon-core 1.4.0 → 2.1.0

package/src/generator.ts

@@ -203,14 +203,70 @@ export interface AskConfirm extends AskBase {
  *   multi: true
  * };
  */
+/**
+ * Rich select option for e-commerce, catalogs, and other common use cases.
+ */
+export type SelectOptionObject = {
+  /** Unique identifier returned when selected */
+  value: string;
+  /** Display label (product name, item title) */
+  label: string;
+  /** Secondary text (short description) */
+  description?: string;
+  /** Image URL (product photo, thumbnail) */
+  image?: string;
+  /** Price in currency units (rendered with locale formatting) */
+  price?: number;
+  /** Original price for showing discounts */
+  originalPrice?: number;
+  /** Currency code (default: USD) */
+  currency?: string;
+  /** Badge text (Sale, New, Low Stock, etc.) */
+  badge?: string;
+  /** Badge color/type for styling */
+  badgeType?: 'default' | 'success' | 'warning' | 'error' | 'info';
+  /** Quantity (for cart items) */
+  quantity?: number;
+  /** Enable +/- quantity controls */
+  adjustable?: boolean;
+  /** Minimum quantity (0 = can remove, default: 1) */
+  minQuantity?: number;
+  /** Maximum quantity allowed */
+  maxQuantity?: number;
+  /** Category for filtering (e.g., 'vegetarian', 'spicy') */
+  category?: string | string[];
+  /** Whether the option is disabled/unavailable */
+  disabled?: boolean;
+  /** Reason for being disabled (Out of stock, etc.) */
+  disabledReason?: string;
+  /** Pre-selected state for multi-select */
+  selected?: boolean;
+  /** Additional metadata (not rendered, returned with selection) */
+  meta?: Record<string, any>;
+};
+
+export type SelectOption = string | SelectOptionObject;
+
 export interface AskSelect extends AskBase {
   ask: 'select';
-  /** Available options */
-  options: Array<string | { value: string; label: string; description?: string }>;
+  /** Available options - simple strings or rich option objects */
+  options: SelectOption[];
   /** Allow selecting multiple options */
   multi?: boolean;
   /** Default selected value(s) */
   default?: string | string[];
+  /** Layout style for rendering options */
+  layout?: 'list' | 'grid' | 'cards';
+  /** Number of columns for grid/cards layout */
+  columns?: number;
+  /** Filter buttons to show (e.g., ['All', 'Vegetarian', 'Vegan']) */
+  filters?: string[];
+  /** Which option field to filter on (default: 'category') */
+  filterField?: string;
+  /** Show search box for filtering options */
+  searchable?: boolean;
+  /** Placeholder text for search box */
+  searchPlaceholder?: string;
 }
 
 /**
@@ -725,8 +781,8 @@ export type StatefulYield = PhotonYield | CheckpointYield;
  *   generator.next(userInput);
  * }
  */
-export function isAskYield(y: PhotonYield): y is AskYield {
-  return 'ask' in y;
+export function isAskYield(y: PhotonYield | any): y is AskYield {
+  return typeof y === 'object' && y !== null && 'ask' in y;
 }
 
 /**
@@ -738,8 +794,8 @@ export function isAskYield(y: PhotonYield): y is AskYield {
  *   generator.next(); // Continue without value
  * }
  */
-export function isEmitYield(y: PhotonYield): y is EmitYield {
-  return 'emit' in y;
+export function isEmitYield(y: PhotonYield | any): y is EmitYield {
+  return typeof y === 'object' && y !== null && 'emit' in y;
 }
 
 /**
@@ -930,9 +986,13 @@ export async function executeGenerator<T>(
       // Continue without providing a value
       result = await generator.next();
     }
-    // Unknown yield type - skip
+    // Handle raw values (strings, numbers, objects without emit/ask)
     else {
-      console.warn('[generator] Unknown yield type:', yielded);
+      if (outputHandler) {
+        await outputHandler({ emit: 'stream', data: yielded } as EmitStream);
+      } else {
+        console.warn('[generator] Unknown yield type without output handler:', yielded);
+      }
       result = await generator.next();
     }
   }

package/src/index.ts

@@ -33,17 +33,18 @@
  * ```
  */
 
-// Core base class with lifecycle hooks
-export { PhotonMCP } from './base.js';
-
-// Dependency management
-export { DependencyManager } from './dependency-manager.js';
-
-// Schema extraction
-export { SchemaExtractor } from './schema-extractor.js';
-
-// CLI formatting
+// ===== RE-EXPORT FROM @portel/cli =====
+// CLI formatting, progress, text utils, fuzzy matching, logging
 export {
+  // Types
+  type OutputFormat,
+  type TextWrapOptions,
+  type FuzzyMatch,
+  type ExecutionContext,
+  type LogLevel,
+  type LoggerOptions,
+
+  // CLI Formatting
   formatOutput,
   detectFormat,
   renderPrimitive,
@@ -60,54 +61,123 @@ export {
   printWarning,
   printHeader,
   STATUS,
-} from './cli-formatter.js';
 
-// Path resolution
-export {
-  resolvePath,
-  listFiles,
-  ensureDir,
-  resolvePhotonPath,
-  listPhotonFiles,
-  ensurePhotonDir,
-  DEFAULT_PHOTON_DIR,
-  type ResolverOptions,
-} from './path-resolver.js';
+  // Progress
+  ProgressRenderer,
+  getProgressRenderer,
+  startSpinner,
+  showProgress,
+  updateProgressMessage,
+  stopProgress,
+  isProgressActive,
 
-// Types
-export * from './types.js';
+  // Execution Context
+  executionContext,
+  runWithContext,
+  getContext,
 
-// MCP Protocol Client - for calling external MCPs from Photons
+  // Text Utils
+  TextUtils,
+
+  // Fuzzy Matching
+  FuzzyMatcher,
+  fuzzyMatch,
+  fuzzyScore,
+  findBestMatch,
+
+  // Logger
+  Logger,
+  createLogger,
+  getLogger,
+} from '@portel/cli';
+
+// ===== RE-EXPORT FROM @portel/mcp =====
+// MCP client, transport, configuration, elicitation
 export {
+  // Types
+  type MCPToolInfo,
+  type MCPToolResult,
+  type MCPTransport,
+  type MCPSourceType,
+  type MissingMCPInfo,
+  type MCPServerConfig,
+  type MCPConfig,
+  type PhotonMCPConfig,
+  type ElicitOptions,
+  type ElicitResult,
+  type PromptHandler,
+  type ElicitHandler,
+
+  // MCP Client
   MCPClient,
+  type MCPClientFactory,
   MCPError,
   MCPNotConnectedError,
   MCPToolError,
   MCPConfigurationError,
   createMCPProxy,
-  type MCPToolInfo,
-  type MCPToolResult,
-  type MCPTransport,
-  type MCPClientFactory,
-  type MCPSourceType,
-  type MissingMCPInfo,
-} from './mcp-client.js';
 
-// MCP SDK Transport - official SDK-based transport implementation
-export {
+  // MCP SDK Transport
   SDKMCPTransport,
   SDKMCPClientFactory,
   loadMCPConfig,
   createSDKMCPClientFactory,
   resolveMCPSource,
-  type MCPServerConfig,
-  type MCPConfig,
-} from './mcp-sdk-transport.js';
+
+  // MCP Configuration
+  PHOTON_CONFIG_DIR,
+  MCP_SERVERS_CONFIG_FILE,
+  loadPhotonMCPConfig,
+  savePhotonMCPConfig,
+  isMCPConfigured,
+  getMCPServerConfig,
+  listMCPServers,
+  setMCPServerConfig,
+  removeMCPServerConfig,
+  toMCPConfig,
+  resolveEnvVars,
+
+  // Elicitation
+  prompt,
+  confirm,
+  elicit,
+  elicitReadline,
+  elicitNativeDialog,
+  setPromptHandler,
+  getPromptHandler,
+  setElicitHandler,
+  getElicitHandler,
+} from '@portel/mcp';
+
+// ===== PHOTON-SPECIFIC EXPORTS =====
+
+// Core base class with lifecycle hooks
+export { PhotonMCP } from './base.js';
+
+// Dependency management
+export { DependencyManager } from './dependency-manager.js';
+
+// Schema extraction
+export { SchemaExtractor } from './schema-extractor.js';
+
+// Path resolution (Photon-specific paths)
+export {
+  resolvePath,
+  listFiles,
+  ensureDir,
+  resolvePhotonPath,
+  listPhotonFiles,
+  ensurePhotonDir,
+  DEFAULT_PHOTON_DIR,
+  type ResolverOptions,
+} from './path-resolver.js';
+
+// Types
+export * from './types.js';
 
 // Generator-based tools with ask/emit pattern
-// See generator.ts for comprehensive documentation
 export {
-  // Type guards - check yield direction
+  // Type guards
   isAskYield,
   isEmitYield,
   isCheckpointYield,
@@ -118,10 +188,10 @@ export {
   isAsyncGeneratorFunction,
   isAsyncGenerator,
 
-  // Executor - runs generators to completion
+  // Executor
   executeGenerator,
 
-  // Ask extraction (for REST API schema generation)
+  // Ask extraction
   extractAsks,
 
   // Built-in providers
@@ -131,7 +201,7 @@ export {
   // Utility
   wrapAsGenerator,
 
-  // Ask yield types (input from user)
+  // Ask yield types
   type AskYield,
   type AskText,
   type AskPassword,
@@ -143,7 +213,11 @@ export {
   type AskForm,
   type AskUrl,
 
-  // Form schema types (for AskForm)
+  // Rich select option types (e-commerce, catalogs)
+  type SelectOption,
+  type SelectOptionObject,
+
+  // Form schema types
   type FormSchema,
   type FormSchemaProperty,
   type FormSchemaArrayProperty,
@@ -152,7 +226,7 @@ export {
   type ElicitAction,
   type FormElicitResult,
 
-  // Emit yield types (output to user)
+  // Emit yield types
   type EmitYield,
   type EmitStatus,
   type EmitProgress,
@@ -163,7 +237,7 @@ export {
   type EmitArtifact,
   type EmitUI,
 
-  // Checkpoint yield type (for stateful workflows)
+  // Checkpoint yield type
   type CheckpointYield,
 
   // Combined types
@@ -176,7 +250,7 @@ export {
   type GeneratorExecutorConfig,
   type ExtractedAsk,
 
-  // Legacy compatibility (deprecated)
+  // Legacy compatibility
   isInputYield,
   isProgressYield,
   isStreamYield,
@@ -191,75 +265,59 @@ export {
   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';
-
-// Photon Runtime Configuration - ~/.photon/mcp-servers.json
+// Stateful Workflow Execution
 export {
-  // Constants
-  PHOTON_CONFIG_DIR,
-  MCP_SERVERS_CONFIG_FILE,
-  // Load/Save
-  loadPhotonMCPConfig,
-  savePhotonMCPConfig,
-  // Query
-  isMCPConfigured,
-  getMCPServerConfig,
-  listMCPServers,
-  // Modify
-  setMCPServerConfig,
-  removeMCPServerConfig,
-  // Utilities
-  toMCPConfig,
-  resolveEnvVars,
-  // Types
-  type PhotonMCPConfig,
-} from './photon-config.js';
-
-// Stateful Workflow Execution - JSONL persistence with checkpoints
-export {
-  // Constants
   RUNS_DIR,
-
-  // State Log - JSONL persistence
   StateLog,
-
-  // Resume state parsing
   parseResumeState,
-
-  // Stateful executor
   executeStatefulGenerator,
   generateRunId,
-
-  // Run management
+  maybeStatefulExecute,
   listRuns,
   getRunInfo,
   deleteRun,
   cleanupRuns,
-
-  // Types re-exported from stateful.ts
   type CheckpointYield as StatefulCheckpointYield,
   type StatefulYield as StatefulWorkflowYield,
   isCheckpointYield as isStatefulCheckpointYield,
   type ResumeState,
   type StatefulExecutorConfig,
   type StatefulExecutionResult,
+  type MaybeStatefulConfig,
+  type MaybeStatefulResult,
 } from './stateful.js';
+
+// Auto-UI System
+export {
+  type UIComponentType,
+  type UILayout,
+  type UIComponent,
+  type AutoUIConfig,
+  extractUIHints,
+  generateUIComponent,
+  suggestComponents,
+  shouldUseCards,
+  shouldUseChart,
+  type UIRenderer,
+  renderUIComponent,
+} from './auto-ui.js';
+
+// CLI UI Renderer
+export {
+  CLIUIRenderer,
+  cliRenderer,
+} from './cli-ui-renderer.js';
+
+// IO Helper API
+export { io, emit, ask } from './io.js';
+
+// ===== SMART RENDERING (HTML/Web UI) =====
+// Design system tokens and utilities
+export * from './design-system/index.js';
+
+// Smart rendering modules for auto-UI generation
+export * from './rendering/index.js';
+
+// ===== UCP (Universal Commerce Protocol) =====
+// Agentic commerce with checkout, identity, orders, and AP2 payments
+export * from './ucp/index.js';