@portel/photon 1.20.1 → 1.21.0

package/dist/loader.js

@@ -8,7 +8,7 @@ import { realpathSync, existsSync, mkdirSync, symlinkSync, readFileSync } from '
 import { readText, readJSON, writeText, writeJSON } from './shared/io.js';
 import { createRequire } from 'module';
 import * as path from 'path';
-import { pathToFileURL } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 import * as crypto from 'crypto';
 import { startToolSpan } from './telemetry/otel.js';
 import { spawn } from 'child_process';
@@ -130,6 +130,38 @@ const cliRenderZone = new CLIRenderZone();
 export function clearRenderZone() {
     cliRenderZone.clear();
 }
+/**
+ * Inject emit-based convenience helpers on a plain-class instance.
+ * Every helper is a thin wrapper around this.emit so generator-yield and
+ * imperative-call styles produce identical wire events.
+ */
+function injectEmitHelpers(instance) {
+    const emit = (data) => instance.emit(data);
+    // Mirrors photon-core base-class render(): UI-feedback formats route to their
+    // dedicated emit events; all other formats go through the render channel.
+    instance.render = (format, value) => {
+        if (format === undefined)
+            return emit({ emit: 'render:clear' });
+        if (format === 'status')
+            return emit(typeof value === 'string'
+                ? { emit: 'status', message: value }
+                : { emit: 'status', ...value });
+        if (format === 'progress')
+            return emit(typeof value === 'number' ? { emit: 'progress', value } : { emit: 'progress', ...value });
+        if (format === 'toast')
+            return emit(typeof value === 'string' ? { emit: 'toast', message: value } : { emit: 'toast', ...value });
+        emit({ emit: 'render', format, value });
+    };
+    instance.toast = (message, opts = {}) => emit({ emit: 'toast', message, ...opts });
+    instance.log = (message, opts = {}) => emit({ emit: 'log', message, level: opts.level ?? 'info', data: opts.data });
+    instance.status = (message) => emit({ emit: 'status', message });
+    instance.progress = (value, message) => emit({ emit: 'progress', value, message });
+    instance.thinking = (active = true) => emit({ emit: 'thinking', active });
+}
+/** Extra regex checks that force 'emit' capability when helper methods are used. */
+function detectEmitHelperUsage(source) {
+    return /this\.(toast|log|status|progress|thinking)\s*\(/.test(source);
+}
 /**
  * Render a formatted value in the CLI using @portel/cli's formatOutput.
  * Uses clear-and-replace semantics — each call overwrites the previous render.
@@ -650,15 +682,12 @@ export class PhotonLoader {
             // Auto-wire ReactiveArray/Map/Set properties for zero-boilerplate reactivity
             // Developers just `import { Array } from '@portel/photon-core'` and use normally
             this.wireReactiveCollections(instance);
+            // Inject format catalog — this.formats
+            this.injectFormatCatalog(instance);
             // Inject @mcp dependencies from source (this.github, this.fs, etc.)
             if (tsContent) {
                 await this.injectMCPDependencies(instance, tsContent, name);
             }
-            // Auto-wrap public methods in @stateful classes to emit events
-            // All method calls automatically produce events with params, result, timestamp
-            if (tsContent) {
-                this.wrapStatefulMethods(instance, tsContent);
-            }
             // Inject MCP client factory if available (enables this.mcp() calls)
             const setMCPFactory = instance.setMCPFactory;
             if (this.mcpClientFactory && typeof setMCPFactory === 'function') {
@@ -682,6 +711,8 @@ export class PhotonLoader {
             // Photon base class already has these built-in, so only inject for plain classes
             if (tsContent && typeof instance.executeTool !== 'function') {
                 const caps = detectCapabilities(tsContent);
+                if (detectEmitHelperUsage(tsContent))
+                    caps.add('emit');
                 if (caps.size > 0) {
                     this.log(`🔍 Detected capabilities for ${name}: ${[...caps].join(', ')}`);
                 }
@@ -727,15 +758,8 @@ export class PhotonLoader {
                             });
                         }
                     };
-                    // Also inject render() — convenience wrapper around emit
-                    instance.render = (format, value) => {
-                        if (format === undefined) {
-                            instance.emit({ emit: 'render:clear' });
-                        }
-                        else {
-                            instance.emit({ emit: 'render', format, value });
-                        }
-                    };
+                    // Inject convenience helpers (render, toast, log, status, progress, thinking)
+                    injectEmitHelpers(instance);
                 }
                 if (caps.has('memory')) {
                     // Inject lazy memory provider — capture baseDir from loader context
@@ -1001,8 +1025,13 @@ export class PhotonLoader {
                     throw initError;
                 }
             }
+            // Auto-wrap public methods in @stateful classes to emit events
+            // Must happen AFTER capability injection so that emit() is available
+            if (tsContent) {
+                this.wrapStatefulMethods(instance, tsContent);
+            }
             // Extract tools, templates, and statics (with schema override support)
-            const { tools, templates, statics, settingsSchema } = await this.extractTools(MCPClass, absolutePath);
+            const { tools, templates, statics, settingsSchema, auth: extractedAuth, } = await this.extractTools(MCPClass, absolutePath);
             // ═══ SETTINGS INJECTION ═══
             // If the photon declared `protected settings = { ... }`, inject persistence + proxy
             if (settingsSchema?.hasSettings &&
@@ -1052,6 +1081,8 @@ export class PhotonLoader {
                 result.icon = classIcon;
             if (isStateful)
                 result.stateful = true;
+            if (extractedAuth)
+                result.auth = extractedAuth;
             // Store class constructor for static method access
             result.classConstructor = MCPClass;
             // Store settings schema for Beam UI
@@ -1123,6 +1154,8 @@ export class PhotonLoader {
         instance._photonResolver = (photonName, instanceName) => {
             return this.resolveAndLoadPhoton(photonName, absolutePath, instanceName);
         };
+        // Inject format catalog — this.formats
+        this.injectFormatCatalog(instance);
         // Wire reactive collections
         this.wireReactiveCollections(instance);
         // Inject @mcp dependencies
@@ -1152,6 +1185,8 @@ export class PhotonLoader {
         // Detect and inject capabilities for plain classes
         if (tsContent && typeof instance.executeTool !== 'function') {
             const caps = detectCapabilities(tsContent);
+            if (detectEmitHelperUsage(tsContent))
+                caps.add('emit');
             this.injectPathHelpers(instance, tsContent);
             if (caps.has('emit')) {
                 instance.emit = (data) => {
@@ -1186,15 +1221,8 @@ export class PhotonLoader {
                         });
                     }
                 };
-                // Also inject render() — convenience wrapper around emit
-                instance.render = (format, value) => {
-                    if (format === undefined) {
-                        instance.emit({ emit: 'render:clear' });
-                    }
-                    else {
-                        instance.emit({ emit: 'render', format, value });
-                    }
-                };
+                // Inject convenience helpers (render, toast, log, status, progress, thinking)
+                injectEmitHelpers(instance);
             }
             if (caps.has('memory')) {
                 const memoryBaseDir = this.baseDir;
@@ -1296,7 +1324,7 @@ export class PhotonLoader {
             }
         }
         // Extract tools and metadata from embedded source (no disk I/O)
-        const { tools, templates, statics, settingsSchema } = await this.extractTools(MCPClass, absolutePath, tsContent);
+        const { tools, templates, statics, settingsSchema, auth: extractedAuth, } = await this.extractTools(MCPClass, absolutePath, tsContent);
         // Settings injection
         if (settingsSchema?.hasSettings && instance.settings && typeof instance.settings === 'object') {
             const instanceName = options?.instanceName || 'default';
@@ -1326,6 +1354,8 @@ export class PhotonLoader {
             result.icon = classIcon;
         if (isStateful)
             result.stateful = true;
+        if (extractedAuth)
+            result.auth = extractedAuth;
         result.classConstructor = MCPClass;
         if (settingsSchema?.hasSettings) {
             result.settingsSchema = settingsSchema;
@@ -1341,6 +1371,14 @@ export class PhotonLoader {
         const match = source.match(/\/\*\*([\s\S]*?)\*\/\s*export\s+default\s+class\b/);
         return match ? match[1] : '';
     }
+    extractAuthTag(source) {
+        const docblock = this.extractClassDocblock(source);
+        // Use \b to avoid matching @author, @authorize, etc.
+        const match = docblock.match(/@auth\b(?:\s+(\S+))?/i);
+        if (!match)
+            return undefined;
+        return match[1]?.trim() || 'required';
+    }
     /**
      * Reload a Photon MCP file (for hot reload)
      */
@@ -1567,7 +1605,13 @@ export class PhotonLoader {
                             }
                         });
                     }
-                    return { tools, templates, statics, settingsSchema: metadata.settingsSchema };
+                    return {
+                        tools,
+                        templates,
+                        statics,
+                        settingsSchema: metadata.settingsSchema,
+                        auth: this.extractAuthTag(source),
+                    };
                 }
                 throw jsonError;
             }
@@ -2241,11 +2285,14 @@ export class PhotonLoader {
             return;
         if (path.dirname(realCurrentPhotonPath) !== path.dirname(resolvedPath))
             return;
-        const linkPath = path.join(this.baseDir, path.basename(resolvedPath));
+        // Symlink into the directory where the current photon's symlink lives
+        // (e.g. ~/.photon/), NOT this.baseDir which may be a different workspace.
+        const symlinkDir = path.dirname(currentPhotonPath);
+        const linkPath = path.join(symlinkDir, path.basename(resolvedPath));
         await this.createSymlinkIfMissing(resolvedPath, linkPath);
         const depName = path.basename(resolvedPath).replace(/\.photon\.(ts|js)$/, '');
         const sourceAssetDir = path.join(path.dirname(resolvedPath), depName);
-        const targetAssetDir = path.join(this.baseDir, depName);
+        const targetAssetDir = path.join(symlinkDir, depName);
         if (existsSync(sourceAssetDir)) {
             await this.createSymlinkIfMissing(sourceAssetDir, targetAssetDir, 'dir');
         }
@@ -2658,6 +2705,39 @@ Run: photon mcp ${mcpName} --config
             if (mcp.instance._photonConfigError) {
                 throw new Error(mcp.instance._photonConfigError);
             }
+            // Enforce @auth at method level — works across ALL transports (CLI, STDIO, HTTP, daemon)
+            const photonAuth = mcp.auth;
+            if (photonAuth === 'required') {
+                const caller = options?.caller;
+                if (!caller || caller.anonymous) {
+                    const inputProvider = options?.inputProvider || this.createInputProvider();
+                    try {
+                        const token = await inputProvider({
+                            ask: 'password',
+                            message: `${mcp.name} requires authentication. Enter your access token:`,
+                        });
+                        if (token && typeof token === 'string') {
+                            options = {
+                                ...options,
+                                caller: {
+                                    id: token.slice(0, 8),
+                                    name: 'authenticated-user',
+                                    anonymous: false,
+                                    claims: { token },
+                                },
+                            };
+                        }
+                        else {
+                            throw new Error(`Authentication required: ${mcp.name} has @auth required but no credentials were provided`);
+                        }
+                    }
+                    catch (e) {
+                        if (e.message?.includes('Authentication required'))
+                            throw e;
+                        throw new Error(`Authentication required: ${mcp.name} has @auth required. Provide credentials via Authorization header, MCP elicitation, or CLI prompt.`);
+                    }
+                }
+            }
             // Intercept auto-generated settings tool
             if (toolName === 'settings' && mcp.instance._settingsBacking) {
                 const result = await this.executeSettingsTool(mcp.instance, parameters, {
@@ -3048,7 +3128,7 @@ Run: photon mcp ${mcpName} --config
                             : emit.type === 'success'
                                 ? '✅'
                                 : 'ℹ';
-                    this.logger.info(`${icon} ${emit.message}`);
+                    process.stdout.write(`${icon} ${emit.message}\n`);
                     break;
                 case 'thinking':
                     if (emit.active) {
@@ -3115,6 +3195,30 @@ Run: photon mcp ${mcpName} --config
      * }
      * ```
      */
+    _formatCatalogCache = null;
+    injectFormatCatalog(instance) {
+        if (instance.formats)
+            return;
+        // Eagerly load once per loader, cached across all photon instances
+        if (!this._formatCatalogCache) {
+            try {
+                const loaderDir = path.dirname(fileURLToPath(import.meta.url));
+                const renderersPath = path.join(loaderDir, 'auto-ui', 'bridge', 'renderers.js');
+                const esmRequire = createRequire(import.meta.url);
+                this._formatCatalogCache = esmRequire(renderersPath).FORMAT_CATALOG;
+            }
+            catch (e) {
+                this.logger.debug('Failed to load format catalog', { error: e?.message });
+                this._formatCatalogCache = {};
+            }
+        }
+        Object.defineProperty(instance, 'formats', {
+            value: this._formatCatalogCache,
+            configurable: true,
+            enumerable: false,
+            writable: false,
+        });
+    }
     wireReactiveCollections(instance) {
         // Get the emit function if available
         const emit = typeof instance.emit === 'function'
@@ -3163,7 +3267,18 @@ Run: photon mcp ${mcpName} --config
         // Get all public method names from the instance
         // Skip runtime-injected methods (emit, render, push, ask) — these are
         // capability methods injected by the loader, not user-defined tools
-        const RUNTIME_METHODS = new Set(['emit', 'render', 'channel', 'ask', 'call']);
+        const RUNTIME_METHODS = new Set([
+            'emit',
+            'render',
+            'channel',
+            'ask',
+            'call',
+            'toast',
+            'log',
+            'status',
+            'progress',
+            'thinking',
+        ]);
         const proto = Object.getPrototypeOf(instance);
         const methodNames = Object.getOwnPropertyNames(proto).filter((name) => {
             // Skip constructor and private/protected methods
@@ -3188,95 +3303,35 @@ Run: photon mcp ${mcpName} --config
             if (typeof original !== 'function')
                 continue;
             instance[methodName] = function (...args) {
-                // Extract parameter names and map arguments to them
-                const paramNames = PhotonLoader.extractParamNames(original);
-                const params = Object.fromEntries(paramNames.map((name, i) => [name, args[i]]));
-                // Call the original method
                 const result = original.apply(this, args);
-                // Attach __meta to returned objects for audit trail
-                const resultObj = result;
-                if (resultObj &&
-                    typeof resultObj === 'object' &&
-                    !Array.isArray(resultObj) &&
-                    !resultObj.__meta) {
-                    const timestamp = new Date().toISOString();
-                    Object.defineProperty(result, '__meta', {
-                        value: {
-                            createdAt: timestamp,
-                            createdBy: methodName,
-                            modifiedAt: null,
-                            modifiedBy: null,
-                            modifications: [],
-                        },
-                        enumerable: false,
-                        writable: true,
-                        configurable: true,
-                    });
-                }
-                // Emit event with complete context
-                const eventData = {
-                    method: methodName,
-                    params,
-                    result,
-                    timestamp: new Date().toISOString(),
-                };
-                if (this.instanceName) {
-                    eventData.instance = this.instanceName;
-                }
-                // Detect array mutations for range-based pagination support (Phase 5)
-                // If result is an object from this.items, add index and array metadata
-                if (result && typeof result === 'object' && Array.isArray(this.items)) {
-                    const index = this.items.findIndex((item) => item === result);
-                    if (index !== -1) {
-                        eventData.index = index;
-                        eventData.totalCount = this.items.length;
-                        // Affected range: just this item
-                        eventData.affectedRange = {
-                            start: index,
-                            end: index + 1,
-                        };
+                const attachMeta = (obj) => {
+                    if (obj && typeof obj === 'object' && !Array.isArray(obj) && !obj.__meta) {
+                        Object.defineProperty(obj, '__meta', {
+                            value: {
+                                createdAt: new Date().toISOString(),
+                                createdBy: methodName,
+                                modifiedAt: null,
+                                modifiedBy: null,
+                                modifications: [],
+                            },
+                            enumerable: false,
+                            writable: true,
+                            configurable: true,
+                        });
                     }
+                };
+                // For async methods, attach __meta to the resolved value, not the Promise
+                if (result && typeof result.then === 'function') {
+                    return result.then((resolved) => {
+                        attachMeta(resolved);
+                        return resolved;
+                    });
                 }
-                // NOTE: Don't emit here - the real emission happens at executeTool level
-                // (line 2362 via outputHandler). This method wrapper is only called during
-                // direct instantiation testing, not in actual MCP execution paths where executeTool
-                // is the proper routing point.
-                //
-                // If we emit here too, we get duplicate messages:
-                // 1. This wrapper emits directly: emit(eventData)
-                // 2. executeTool emits via outputHandler: outputHandler(eventData)
-                // Both route to daemon, causing double notifications.
+                attachMeta(result);
                 return result;
             };
         }
     }
-    /**
-     * Extract parameter names from a function by parsing its signature
-     *
-     * Examples:
-     * - (text, priority = 'medium') => ['text', 'priority']
-     * - (id) => ['id']
-     * - () => []
-     */
-    static extractParamNames(fn) {
-        const fnStr = fn.toString();
-        // Match parameters inside parentheses: ( ... )
-        const match = fnStr.match(/\(([^)]*)\)/);
-        if (!match?.[1]) {
-            return [];
-        }
-        return match[1]
-            .split(',')
-            .map((param) => {
-            const cleaned = param
-                .trim()
-                .split('=')[0] // Remove default value
-                .split(':')[0] // Remove type annotations
-                .trim();
-            return cleaned;
-        })
-            .filter((name) => name && name !== 'this');
-    }
     /**
      * Extract @mcp dependencies from source and inject them as instance properties
      *