@portel/photon-core 2.9.2 → 2.9.4

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, PhotonDependency, CLIDependency, ResolvedInjection, PhotonAssets, UIAsset, PromptAsset, ResourceAsset, ConfigSchema, ConfigParam } from './types.js';
+import { ExtractedSchema, ConstructorParam, TemplateInfo, StaticInfo, OutputFormat, YieldInfo, MCPDependency, PhotonDependency, CLIDependency, ResolvedInjection, PhotonAssets, UIAsset, PromptAsset, ResourceAsset, ConfigSchema, ConfigParam, SettingsSchema, SettingsProperty, NotificationSubscription } from './types.js';
 import { parseDuration, parseRate } from './utils/duration.js';
 import { builtinRegistry, type MiddlewareDeclaration } from './middleware.js';
 
@@ -18,8 +18,12 @@ export interface ExtractedMetadata {
   tools: ExtractedSchema[];
   templates: TemplateInfo[];
   statics: StaticInfo[];
-  /** Configuration schema from configure() method */
+  /** Settings schema from `protected settings = { ... }` property */
+  settingsSchema?: SettingsSchema;
+  /** @deprecated Configuration schema from configure() method */
   configSchema?: ConfigSchema;
+  /** Notification subscription from @notify-on tag */
+  notificationSubscriptions?: NotificationSubscription;
 }
 
 /**
@@ -47,13 +51,19 @@ export class SchemaExtractor {
     const templates: TemplateInfo[] = [];
     const statics: StaticInfo[] = [];
 
-    // Configuration schema tracking
+    // Settings schema tracking (new property-based approach)
+    let settingsSchema: SettingsSchema | undefined;
+
+    // Configuration schema tracking (deprecated method-based approach)
     let configSchema: ConfigSchema = {
       hasConfigureMethod: false,
       hasGetConfigMethod: false,
       params: [],
     };
 
+    // Notification subscriptions tracking (from @notify-on tag)
+    let notificationSubscriptions: NotificationSubscription | undefined;
+
     try {
       // If source doesn't contain a class declaration, wrap it in one
       let sourceToParse = source;
@@ -70,7 +80,7 @@ export class SchemaExtractor {
       );
 
       // Helper to process a method declaration
-      const processMethod = (member: ts.MethodDeclaration) => {
+      const processMethod = (member: ts.MethodDeclaration, isStatefulClass: boolean = false) => {
         const methodName = member.name.getText(sourceFile);
 
         // Skip private methods (prefixed with _)
@@ -78,32 +88,32 @@ export class SchemaExtractor {
           return;
         }
 
-        // Handle configuration convention methods specially
+        // Track configure/getConfig for backward compat metadata (deprecated)
+        // These are no longer hidden — they become normal visible tools
         if (methodName === 'configure') {
           configSchema.hasConfigureMethod = true;
-          const jsdoc = this.getJSDocComment(member, sourceFile);
-          configSchema.description = this.extractDescription(jsdoc);
+          const jsdocConfig = this.getJSDocComment(member, sourceFile);
+          configSchema.description = this.extractDescription(jsdocConfig);
 
-          // Extract configure() parameters as config schema
           const paramsType = this.getFirstParameterType(member, sourceFile);
           if (paramsType) {
-            const { properties, required } = this.buildSchemaFromType(paramsType, sourceFile);
-            const paramDocs = this.extractParamDocs(jsdoc);
+            const { properties: configProps, required: configRequired } = this.buildSchemaFromType(paramsType, sourceFile);
+            const paramDocs = this.extractParamDocs(jsdocConfig);
 
-            configSchema.params = Object.keys(properties).map(name => ({
+            configSchema.params = Object.keys(configProps).map(name => ({
               name,
-              type: properties[name].type || 'string',
-              description: paramDocs.get(name) || properties[name].description,
-              required: required.includes(name),
-              defaultValue: properties[name].default,
+              type: configProps[name].type || 'string',
+              description: paramDocs.get(name) || configProps[name].description,
+              required: configRequired.includes(name),
+              defaultValue: configProps[name].default,
             }));
           }
-          return; // Don't add configure() as a tool
+          // Fall through — configure() is now a normal tool (not hidden)
         }
 
         if (methodName === 'getConfig') {
           configSchema.hasGetConfigMethod = true;
-          return; // Don't add getConfig() as a tool
+          // Fall through — getConfig() is now a normal tool (not hidden)
         }
 
         const jsdoc = this.getJSDocComment(member, sourceFile);
@@ -212,6 +222,19 @@ export class SchemaExtractor {
           // Check for static keyword on the method
           const isStaticMethod = member.modifiers?.some(m => m.kind === ts.SyntaxKind.StaticKeyword) || false;
 
+          // Event emission for @stateful classes: all public methods emit events automatically
+          const emitsEventData = isStatefulClass ? {
+            emitsEvent: true,
+            eventName: methodName,
+            eventPayload: {
+              method: 'string',
+              params: 'object',
+              result: 'any',
+              timestamp: 'string',
+              instance: 'string',
+            },
+          } : {};
+
           tools.push({
             name: methodName,
             description,
@@ -246,15 +269,123 @@ export class SchemaExtractor {
             ...(deprecated !== undefined ? { deprecated } : {}),
             // Unified middleware declarations (new — runtime uses this)
             ...(middleware.length > 0 ? { middleware } : {}),
+            // Event emission (for @stateful classes)
+            ...emitsEventData,
+          });
+        }
+      };
+
+      // Helper to extract settings from a `protected settings = { ... }` property
+      const processSettingsProperty = (member: ts.PropertyDeclaration, classNode: ts.ClassDeclaration) => {
+        const name = member.name.getText(sourceFile);
+        if (name !== 'settings') return;
+
+        // Must be protected
+        const isProtected = member.modifiers?.some(
+          m => m.kind === ts.SyntaxKind.ProtectedKeyword
+        );
+        if (!isProtected) return;
+
+        // Must have an object literal initializer
+        if (!member.initializer || !ts.isObjectLiteralExpression(member.initializer)) return;
+
+        // Get class-level JSDoc for @property descriptions
+        const classJsdoc = this.getJSDocComment(classNode as any, sourceFile);
+        const propertyDocs = new Map<string, string>();
+        const propertyRegex = /@property\s+(\w+)\s+(.*?)(?=\n\s*\*\s*@|\n\s*\*\/|\n\s*\*\s*$)/gs;
+        let propMatch: RegExpExecArray | null;
+        while ((propMatch = propertyRegex.exec(classJsdoc)) !== null) {
+          propertyDocs.set(propMatch[1], propMatch[2].trim());
+        }
+
+        const properties: SettingsProperty[] = [];
+
+        for (const prop of member.initializer.properties) {
+          if (!ts.isPropertyAssignment(prop)) continue;
+          const propName = prop.name.getText(sourceFile);
+
+          // Determine type and default from the initializer
+          let type = 'string';
+          let defaultValue: any = undefined;
+          let required = false;
+
+          const init = prop.initializer;
+
+          if (ts.isNumericLiteral(init)) {
+            type = 'number';
+            defaultValue = Number(init.text);
+          } else if (ts.isStringLiteral(init)) {
+            type = 'string';
+            defaultValue = init.text;
+          } else if (init.kind === ts.SyntaxKind.TrueKeyword) {
+            type = 'boolean';
+            defaultValue = true;
+          } else if (init.kind === ts.SyntaxKind.FalseKeyword) {
+            type = 'boolean';
+            defaultValue = false;
+          } else if (init.kind === ts.SyntaxKind.UndefinedKeyword) {
+            // `key: undefined` — required, type inferred from as-expression or defaults to string
+            required = true;
+          } else if (ts.isAsExpression(init)) {
+            // `key: undefined as string | undefined` or `key: 5 as number`
+            const innerInit = init.expression;
+            const isUndefined = innerInit.kind === ts.SyntaxKind.UndefinedKeyword ||
+              (ts.isIdentifier(innerInit) && innerInit.text === 'undefined');
+            if (isUndefined) {
+              required = true;
+            } else if (ts.isNumericLiteral(innerInit)) {
+              type = 'number';
+              defaultValue = Number(innerInit.text);
+            } else if (ts.isStringLiteral(innerInit)) {
+              type = 'string';
+              defaultValue = innerInit.text;
+            } else if (innerInit.kind === ts.SyntaxKind.TrueKeyword || innerInit.kind === ts.SyntaxKind.FalseKeyword) {
+              type = 'boolean';
+              defaultValue = innerInit.kind === ts.SyntaxKind.TrueKeyword;
+            }
+            // Try to get type from the as-expression type annotation
+            const typeText = init.type.getText(sourceFile).replace(/\s*\|\s*undefined/g, '').trim();
+            if (typeText === 'number') type = 'number';
+            else if (typeText === 'boolean') type = 'boolean';
+            else if (typeText === 'string') type = 'string';
+          } else if (ts.isArrayLiteralExpression(init)) {
+            type = 'array';
+            defaultValue = [];
+          }
+
+          properties.push({
+            name: propName,
+            type,
+            description: propertyDocs.get(propName),
+            default: defaultValue,
+            required,
           });
         }
+
+        settingsSchema = {
+          hasSettings: true,
+          properties,
+          description: propertyDocs.size > 0 ? 'Photon settings' : undefined,
+        };
       };
 
       // Visit all nodes in the AST
       const visit = (node: ts.Node) => {
         // Look for class declarations
         if (ts.isClassDeclaration(node)) {
+          // Check if this class has @stateful decorator
+          const classJsdoc = this.getJSDocComment(node as any, sourceFile);
+          const isStatefulClass = /@stateful\b/i.test(classJsdoc);
+
+          // Extract notification subscriptions from @notify-on tag
+          notificationSubscriptions = this.extractNotifyOn(classJsdoc);
+
           node.members.forEach((member) => {
+            // Detect `protected settings = { ... }` property
+            if (ts.isPropertyDeclaration(member)) {
+              processSettingsProperty(member, node);
+            }
+
             // Process all public methods (sync or async)
             // Skip private/protected — only public methods become tools
             if (ts.isMethodDeclaration(member)) {
@@ -262,7 +393,7 @@ export class SchemaExtractor {
                 m => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword
               );
               if (!isPrivate) {
-                processMethod(member);
+                processMethod(member, isStatefulClass);
               }
             }
           });
@@ -276,11 +407,23 @@ export class SchemaExtractor {
       console.error('Failed to parse TypeScript source:', error.message);
     }
 
-    // Only include configSchema if there's a configure() method
     const result: ExtractedMetadata = { tools, templates, statics };
+
+    // Include settingsSchema if detected
+    if (settingsSchema) {
+      result.settingsSchema = settingsSchema;
+    }
+
+    // Include configSchema if there's a configure() method (deprecated)
     if (configSchema.hasConfigureMethod) {
       result.configSchema = configSchema;
     }
+
+    // Include notification subscriptions if detected
+    if (notificationSubscriptions) {
+      result.notificationSubscriptions = notificationSubscriptions;
+    }
+
     return result;
   }
 
@@ -1230,9 +1373,6 @@ export class SchemaExtractor {
         if (constraints.pattern !== undefined) {
           s.pattern = constraints.pattern;
         }
-        if (constraints.format !== undefined) {
-          s.format = constraints.format;
-        }
       } else if (s.type === 'array') {
         if (constraints.min !== undefined) {
           s.minItems = constraints.min;
@@ -1246,6 +1386,9 @@ export class SchemaExtractor {
       }
 
       // Apply type-agnostic constraints
+      if (constraints.format !== undefined) {
+        s.format = constraints.format;
+      }
       if (constraints.default !== undefined) {
         s.default = constraints.default;
       }
@@ -1352,6 +1495,30 @@ export class SchemaExtractor {
     return /@async\b/i.test(jsdocContent);
   }
 
+  /**
+   * Extract notification subscriptions from @notify-on tag
+   * Specifies which event types this photon is interested in
+   * Format: @notify-on mentions, deadlines, errors
+   */
+  private extractNotifyOn(jsdocContent: string): NotificationSubscription | undefined {
+    const notifyMatch = jsdocContent.match(/@notify-on\s+([^\n]+)/i);
+    if (!notifyMatch) {
+      return undefined;
+    }
+
+    // Parse comma-separated event types
+    const watchFor = notifyMatch[1]
+      .split(',')
+      .map(s => s.trim())
+      .filter(s => s.length > 0);
+
+    if (watchFor.length === 0) {
+      return undefined;
+    }
+
+    return { watchFor };
+  }
+
   // ═══════════════════════════════════════════════════════════════════════════════
   // DAEMON FEATURE EXTRACTION
   // ═══════════════════════════════════════════════════════════════════════════════
@@ -1815,23 +1982,29 @@ export class SchemaExtractor {
   extractPhotonDependencies(source: string): PhotonDependency[] {
     const dependencies: PhotonDependency[] = [];
 
-    // Match @photon <name> <source> pattern
+    // Match @photon <name> <source> pattern, where source may include :instanceName suffix
+    // e.g., @photon homeTodos todo:home → source='todo', instanceName='home'
     // Source ends at: newline, end of comment (*), or @ (next tag)
-    const photonRegex = /@photon\s+(\w+)\s+([^\s*@\n]+)/g;
+    const photonRegex = /@photon\s+(\w+)\s+([^\s*@\n:]+)(?::(\w[\w-]*))?/g;
 
     let match;
     while ((match = photonRegex.exec(source)) !== null) {
-      const [, name, rawSource] = match;
+      const [, name, rawSource, instanceName] = match;
       const photonSource = rawSource.trim();
 
       // Determine source type
       const sourceType = this.classifyPhotonSource(photonSource);
 
-      dependencies.push({
+      const dep: PhotonDependency = {
         name,
         source: photonSource,
         sourceType,
-      });
+      };
+      if (instanceName) {
+        dep.instanceName = instanceName;
+      }
+
+      dependencies.push(dep);
     }
 
     return dependencies;

package/src/types.ts

@@ -191,6 +191,26 @@ export interface ExtractedSchema {
 
   /** When true, method uses individual params instead of a single params object */
   simpleParams?: boolean;
+
+  // ═══ EVENT EMISSION ═══
+
+  /**
+   * True if this method automatically emits an event on execution
+   * (for @stateful classes, all public methods emit automatically)
+   */
+  emitsEvent?: boolean;
+
+  /**
+   * Event name that will be emitted when this method is called
+   * For @stateful classes, defaults to the method name (e.g., 'add', 'done')
+   */
+  eventName?: string;
+
+  /**
+   * Event payload structure — what data will be sent with the event
+   * Typically mirrors the return type of the method
+   */
+  eventPayload?: Record<string, string>;
 }
 
 export interface PhotonClass {
@@ -302,6 +322,8 @@ export interface PhotonDependency {
   source: string;
   /** Resolved source type */
   sourceType: 'marketplace' | 'github' | 'npm' | 'local';
+  /** Named instance to load (e.g., 'home' from `@photon homeTodos todo:home`) */
+  instanceName?: string;
 }
 
 /**
@@ -487,6 +509,8 @@ export interface PhotonClassExtended extends PhotonClass {
   assets?: PhotonAssets;
   /** Names of injected @photon dependencies (for client-side event routing) */
   injectedPhotons?: string[];
+  /** Settings schema if the photon has `protected settings = { ... }` */
+  settingsSchema?: SettingsSchema;
 }
 
 /** @deprecated Use PhotonClassExtended instead */
@@ -642,10 +666,56 @@ export interface WorkflowRun {
 }
 
 // ══════════════════════════════════════════════════════════════════════════════
-// CONFIGURATION CONVENTION
+// SETTINGS (first-class property-driven configuration)
+// ══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * A single property in a photon's settings declaration
+ */
+export interface SettingsProperty {
+  /** Property name */
+  name: string;
+  /** JSON Schema type (string, number, boolean, etc.) */
+  type: string;
+  /** Description from @property JSDoc tag */
+  description?: string;
+  /** Default value from the object literal (undefined means elicitation required) */
+  default?: any;
+  /** True if default is undefined — runtime must elicit this value */
+  required: boolean;
+}
+
+/**
+ * Settings schema extracted from a photon's `protected settings = { ... }` property
+ *
+ * Example:
+ * ```typescript
+ * /**
+ *  * @property wipLimit WIP limit for in-progress tasks (1-20)
+ *  * @property staleTaskDays Days before a task is considered stale
+ *  *\/
+ * protected settings = {
+ *   wipLimit: 5,
+ *   staleTaskDays: 7,
+ *   projectsRoot: undefined as string | undefined,
+ * };
+ * ```
+ */
+export interface SettingsSchema {
+  /** Whether a settings property was detected */
+  hasSettings: boolean;
+  /** Individual settings properties */
+  properties: SettingsProperty[];
+  /** Description from class-level JSDoc */
+  description?: string;
+}
+
+// ══════════════════════════════════════════════════════════════════════════════
+// CONFIGURATION CONVENTION (deprecated — use settings property instead)
 // ══════════════════════════════════════════════════════════════════════════════
 
 /**
+ * @deprecated Use SettingsProperty instead
  * Configuration parameter extracted from configure() method
  */
 export interface ConfigParam {
@@ -662,35 +732,8 @@ export interface ConfigParam {
 }
 
 /**
+ * @deprecated Use SettingsSchema instead
  * Configuration schema extracted from a Photon's configure() method
- *
- * The configure() method is a by-convention method for photon configuration.
- * Similar to how main() makes a photon a UI application, configure() makes
- * it a configurable photon.
- *
- * When present, the framework will:
- * 1. Extract parameter schema from the method signature
- * 2. Present a configuration UI during install/setup
- * 3. Store config at ~/.photon/{photonName}/config.json
- * 4. Make config available via getConfig()
- *
- * Example:
- * ```typescript
- * export default class MyPhoton extends Photon {
- *   async configure(params: {
- *     apiEndpoint: string;
- *     maxRetries?: number;
- *   }) {
- *     // Save config - framework handles storage
- *     return { success: true };
- *   }
- *
- *   async getConfig() {
- *     // Read config - framework handles loading
- *     return loadPhotonConfig('my-photon');
- *   }
- * }
- * ```
  */
 export interface ConfigSchema {
   /** Whether configure() method exists */
@@ -702,3 +745,31 @@ export interface ConfigSchema {
   /** Description from configure() JSDoc */
   description?: string;
 }
+
+// ══════════════════════════════════════════════════════════════════════════════
+// NOTIFICATION SUBSCRIPTIONS (@notify-on tag)
+// ══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Notification subscription declaration extracted from @notify-on tag
+ * Specifies which event types this photon cares about for notifications
+ */
+export interface NotificationSubscription {
+  /** Event types this photon wants to be notified about */
+  watchFor: string[];
+}
+
+/**
+ * Notification metadata attached to method return values via __notification property
+ * Specifies priority and type of notification when an event occurs
+ */
+export interface NotificationMetadata {
+  /** Type of notification (mentions, deadline, error, etc.) */
+  type: string;
+  /** Priority level for display and handling */
+  priority: 'critical' | 'warning' | 'info';
+  /** Optional message to display */
+  message?: string;
+  /** Optional tags for additional filtering */
+  tags?: string[];
+}