@portel/photon-core 2.9.1 → 2.9.3

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 } from './types.js';
 import { parseDuration, parseRate } from './utils/duration.js';
 import { builtinRegistry, type MiddlewareDeclaration } from './middleware.js';
 
@@ -18,7 +18,9 @@ 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;
 }
 
@@ -47,7 +49,10 @@ 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,
@@ -78,38 +83,42 @@ 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);
 
         // Skip @internal methods — hidden from LLM and sidebar
-        if (/@internal\b/.test(jsdoc)) {
+        // Exception: daemon-feature methods (@scheduled, @webhook) must still
+        // be registered in tools so the runtime can wire up cron jobs/webhooks.
+        const isInternal = /@internal\b/.test(jsdoc);
+        const hasDaemonFeature = /@scheduled\b/.test(jsdoc) || /@webhook\b/.test(jsdoc) || /@cron\b/.test(jsdoc) || /^scheduled/.test(methodName);
+        if (isInternal && !hasDaemonFeature) {
           return;
         }
 
@@ -212,6 +221,7 @@ export class SchemaExtractor {
             name: methodName,
             description,
             inputSchema,
+            ...(isInternal ? { internal: true } : {}),
             ...(outputFormat ? { outputFormat } : {}),
             ...(layoutHints ? { layoutHints } : {}),
             ...(buttonLabel ? { buttonLabel } : {}),
@@ -245,11 +255,110 @@ export class SchemaExtractor {
         }
       };
 
+      // 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)) {
           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)) {
@@ -271,11 +380,18 @@ 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;
     }
+
     return result;
   }
 
@@ -1225,9 +1341,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;
@@ -1241,6 +1354,9 @@ export class SchemaExtractor {
       }
 
       // Apply type-agnostic constraints
+      if (constraints.format !== undefined) {
+        s.format = constraints.format;
+      }
       if (constraints.default !== undefined) {
         s.default = constraints.default;
       }
@@ -1810,23 +1926,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

@@ -302,6 +302,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 +489,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 +646,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 +712,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 */