@portel/photon 1.29.0 → 1.31.0

package/dist/auto-ui/beam.js

@@ -110,6 +110,7 @@ import { loadConfig as loadConfigFromModule, saveConfig as saveConfigFromModule,
 import { extractClassMetadataFromSource as extractClassMetadataFromModule, applyMethodVisibility as applyMethodVisibilityFromModule, extractCspFromSource as extractCspFromModule, prettifyName as prettifyNameFromModule, backfillEnvDefaults as backfillEnvDefaultsFromModule, } from './beam/class-metadata.js';
 import { StartupSequencer } from './beam/startup.js';
 import { SubscriptionManager } from './beam/subscription.js';
+import { ExternalMCPManager } from './beam/external-mcp-manager.js';
 import { handleMarketplaceRoutes } from './beam/routes/api-marketplace.js';
 import { handleBrowseRoutes } from './beam/routes/api-browse.js';
 import { handleConfigRoutes } from './beam/routes/api-config.js';
@@ -123,12 +124,8 @@ const getConfigFilePath = getConfigFilePathFromModule;
 // BEAM CONTEXT — all module-level mutable state lives here
 // ═══════════════════════════════════════════════════════════════════════════════
 class BeamContext {
-    /** External MCP server metadata */
-    externalMCPs = [];
-    /** Transport-level clients for external MCPs */
-    externalMCPClients = new Map();
-    /** SDK Client instances for tool calls with structuredContent */
-    externalMCPSDKClients = new Map();
+    /** External MCP lifecycle: list, transport clients, SDK clients, add/remove. */
+    mcp = new ExternalMCPManager();
     /**
      * Notification subscriptions per photon.
      * Key: photon name, Value: list of event types this photon cares about
@@ -140,12 +137,24 @@ class BeamContext {
      * so dynamically discovered photons can be subscribed without duplicates.
      */
     subscribedStateChannels = new Set();
+    // Backward-compat field-name accessors. The 24 callsites that read
+    // ctx.externalMCPs / ctx.externalMCPClients / ctx.externalMCPSDKClients
+    // continue to work; they now flow through the manager.
+    get externalMCPs() {
+        return this.mcp.externalMCPs;
+    }
+    get externalMCPClients() {
+        return this.mcp.externalMCPClients;
+    }
+    get externalMCPSDKClients() {
+        return this.mcp.externalMCPSDKClients;
+    }
     /** Convenience accessor matching the shape expected by external-mcp module */
     get externalMCPState() {
         return {
-            externalMCPs: this.externalMCPs,
-            externalMCPClients: this.externalMCPClients,
-            externalMCPSDKClients: this.externalMCPSDKClients,
+            externalMCPs: this.mcp.externalMCPs,
+            externalMCPClients: this.mcp.externalMCPClients,
+            externalMCPSDKClients: this.mcp.externalMCPSDKClients,
         };
     }
 }
@@ -753,7 +762,10 @@ export async function startBeam(rawWorkingDir, port) {
                         // Check if method has @ui tag matching this id
                         const methodSource = schemaSource.match(new RegExp(`@ui\\s+${uiId}[\\s\\n]*\\*/[\\s\\n]*(?:async\\s+)?${schema.name}\\s*\\(`, 'm'));
                         if (methodSource) {
-                            uiAssets.push({ id: uiId, linkedTool: schema.name });
+                            // Synthetic record for sidebar linking — `path` isn't available
+                            // here (source-only inference), but downstream readers only
+                            // touch id/linkedTool. Empty string keeps the UIAsset contract.
+                            uiAssets.push({ id: uiId, path: '', linkedTool: schema.name });
                         }
                     });
                 }
@@ -836,7 +848,6 @@ export async function startBeam(rawWorkingDir, port) {
             const mainMethod = methods.find((m) => m.name === 'main');
             // Extract class-level metadata — reuse source already read
             const classMetadata = extractClassMetadataFromSource(schemaSource);
-            // Extract class-level @csp metadata and apply to all UI assets
             const cspData = extractCspFromSource(schemaSource);
             if (cspData['__class__'] && mcp.assets?.ui) {
                 for (const uiAsset of mcp.assets.ui) {
@@ -937,7 +948,8 @@ export async function startBeam(rawWorkingDir, port) {
             return null;
         const photonDir = path.dirname(photon.path);
         const photonBaseName = path.basename(photon.path, '.photon.ts');
-        const asset = photon.assets?.ui?.find((u) => u.id === uiId);
+        // assets only live on configured photons
+        const asset = photon.configured ? photon.assets?.ui?.find((u) => u.id === uiId) : undefined;
         let resolved;
         if (asset?.resolvedPath) {
             resolved = {
@@ -1387,10 +1399,12 @@ export async function startBeam(rawWorkingDir, port) {
                     res.end(`Photon not found: ${photonName}`);
                     return;
                 }
-                const label = photon?.label ||
+                const label = photon.label ||
                     photonName.charAt(0).toUpperCase() + photonName.slice(1).replace(/-/g, ' ');
-                const description = photon?.description || `${label} - Photon App`;
-                const iconValue = photon?.icon || '📦';
+                // `description` and `icon` only live on configured photons; an unconfigured
+                // entry falls back to the auto-built defaults below.
+                const description = (photon.configured && photon.description) || `${label} - Photon App`;
+                const iconValue = (photon.configured && photon.icon) || '📦';
                 const encodedName = encodeURIComponent(photonName);
                 // Sanitize strings for safe embedding in HTML
                 const safeLabel = label.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] || c);
@@ -1874,6 +1888,94 @@ export async function startBeam(rawWorkingDir, port) {
                 }
                 return;
             }
+            // Web route proxy: /web/{photonName}/{...path} dispatches to the photon's
+            // @get/@post handlers. The prefix is stripped before dispatch so that the
+            // photon's routes look like they're running at the root. HTML responses
+            // get a fetch interceptor injected so that absolute fetch('/api/foo')
+            // calls inside the photon's UI are transparently rewritten to
+            // /web/{photonName}/api/foo by the browser.
+            if (url.pathname.startsWith('/web/')) {
+                const [, , photonName, ...pathParts] = url.pathname.split('/');
+                const photonPath = '/' + pathParts.join('/') || '/';
+                const photonClass = photonName ? photonMCPs.get(photonName) : undefined;
+                const httpRoutes = photonClass?._httpRoutes;
+                const route = httpRoutes?.find((r) => r.method === (req.method || 'GET') && r.path === photonPath);
+                if (route && photonClass?.instance) {
+                    const fn = photonClass.instance[route.handler];
+                    if (typeof fn === 'function') {
+                        try {
+                            let bodyBuffer = Buffer.alloc(0);
+                            await new Promise((resolve) => {
+                                req.on('data', (chunk) => {
+                                    bodyBuffer = Buffer.concat([bodyBuffer, chunk]);
+                                });
+                                req.on('end', resolve);
+                            });
+                            const internalUrl = new URL(photonPath + (url.search || ''), `http://${req.headers.host || 'localhost'}`);
+                            const webReq = new Request(internalUrl.toString(), {
+                                method: req.method,
+                                headers: req.headers,
+                                ...(req.method !== 'GET' && bodyBuffer.length > 0 ? { body: bodyBuffer } : {}),
+                            });
+                            const result = await fn.call(photonClass.instance, webReq);
+                            if (result instanceof Response) {
+                                const contentType = result.headers.get('content-type') || '';
+                                const responseHeaders = {};
+                                result.headers.forEach((value, key) => {
+                                    responseHeaders[key] = value;
+                                });
+                                let body = Buffer.from(await result.arrayBuffer());
+                                // Inject fetch interceptor into HTML responses so relative API
+                                // calls inside the photon UI resolve via the /web/ prefix.
+                                if (contentType.includes('text/html')) {
+                                    const prefix = `/web/${photonName}`;
+                                    const interceptor = `<script>
+(function(){
+  const _prefix="${prefix}";
+  const _origFetch=window.fetch;
+  window.fetch=function(input,init){
+    if(typeof input==='string'&&input.startsWith('/')&&!input.startsWith(_prefix))
+      input=_prefix+input;
+    return _origFetch(input,init);
+  };
+  const _origOpen=XMLHttpRequest.prototype.open;
+  XMLHttpRequest.prototype.open=function(m,u,...a){
+    if(typeof u==='string'&&u.startsWith('/')&&!u.startsWith(_prefix))u=_prefix+u;
+    return _origOpen.call(this,m,u,...a);
+  };
+})();
+</script>`;
+                                    const bodyStr = body.toString('utf-8').replace('<head>', '<head>' + interceptor);
+                                    body = Buffer.from(bodyStr, 'utf-8');
+                                    responseHeaders['content-length'] = String(body.length);
+                                }
+                                res.writeHead(result.status, responseHeaders);
+                                res.end(body);
+                                return;
+                            }
+                            // Plain value — negotiate content type and render
+                            const { negotiateAccept } = await import('../format/registry.js');
+                            const { getDefaultRegistry } = await import('../format/seed.js');
+                            const acceptHeader = req.headers['accept'];
+                            const rendered = negotiateAccept({
+                                accept: typeof acceptHeader === 'string' ? acceptHeader : undefined,
+                                declaredFormat: route.format,
+                                value: result,
+                                registry: getDefaultRegistry(),
+                            });
+                            res.writeHead(200, { 'Content-Type': rendered.mime });
+                            res.end(typeof rendered.body === 'string' ? rendered.body : Buffer.from(rendered.body));
+                            return;
+                        }
+                        catch (err) {
+                            res.writeHead(500).end(err?.message ?? 'Internal Server Error');
+                            return;
+                        }
+                    }
+                }
+                res.writeHead(404).end('Not Found');
+                return;
+            }
             // Default route: Serve Lit App
             if (url.pathname === '/' || !url.pathname.startsWith('/api')) {
                 try {
@@ -1911,6 +2013,7 @@ export async function startBeam(rawWorkingDir, port) {
     const activeLoads = new Set(); // Photons currently being loaded (prevents concurrent duplicate loads)
     const pendingAfterLoad = new Set(); // File changes that arrived while a load was active; re-triggered after
     const symlinkWatchedDirs = new Set(); // Track which source dirs already have watchers (prevents duplicates on re-setup)
+    const autoRetried = new Set(); // Photons that have already had one auto-retry after a load failure
     // Set up file watchers for a symlinked photon's real source directory and asset folder.
     // Called both at startup and after a previously-errored symlinked photon recovers.
     const setupSymlinkWatcher = (photonName, photonPath) => {
@@ -2169,12 +2272,13 @@ export async function startBeam(rawWorkingDir, port) {
                     }
                     try {
                         // Load or reload the photon
-                        const mcp = isNewPhoton
+                        const mcp = (isNewPhoton
                             ? await loader.loadFile(photonPath)
-                            : await loader.reloadFile(photonPath);
+                            : await loader.reloadFile(photonPath));
                         if (!mcp.instance)
                             throw new Error('Failed to create instance');
                         photonMCPs.set(photonName, mcp);
+                        autoRetried.delete(photonName); // Clear retry flag on success
                         // Re-extract schema - use extractAllFromSource to get both tools and templates
                         const extractor = new SchemaExtractor();
                         const reloadSource = await readText(photonPath);
@@ -2373,6 +2477,40 @@ export async function startBeam(rawWorkingDir, port) {
                             }
                             return;
                         }
+                        // esbuild subprocess crash: the in-process service is permanently
+                        // dead — cache clears don't help. Respawn Beam so the next
+                        // file-save gets a fresh compiler. The browser's SSE reconnect
+                        // loop handles the brief disconnect transparently.
+                        const isServiceCrash = errorMsg.includes('The service was stopped') ||
+                            errorMsg.includes('The service is no longer running');
+                        if (isServiceCrash) {
+                            logger.warn(`Compiler service crashed — restarting Beam (${process.argv.slice(1).join(' ')})`);
+                            const { spawn } = await import('child_process');
+                            spawn(process.execPath, process.argv.slice(1), {
+                                stdio: 'inherit',
+                                env: process.env,
+                                detached: false,
+                            });
+                            process.exit(0);
+                            return;
+                        }
+                        // On the first failure, clear the build cache and retry automatically.
+                        // This recovers from stale artifacts or dependency issues without
+                        // requiring the user to touch the file or restart Beam.
+                        if (!autoRetried.has(photonName)) {
+                            autoRetried.add(photonName);
+                            logger.info(`🔄 ${photonName} failed to load, clearing cache and retrying...`);
+                            try {
+                                const retryPath = photons.find((p) => p.name === photonName)?.path || photonPath;
+                                await loader.clearCacheForFile(retryPath);
+                            }
+                            catch {
+                                // best-effort
+                            }
+                            setTimeout(() => void handleFileChange(photonName), 500);
+                            return;
+                        }
+                        // Second failure — give up and surface the error
                         logger.error(`Hot reload failed for ${photonName}: ${errorMsg}`);
                         broadcastToBeam('beam/error', {
                             type: 'hot-reload-error',
@@ -2533,7 +2671,7 @@ export async function startBeam(rawWorkingDir, port) {
     }
     // Load external MCPs from config
     const externalMCPList = await loadExternalMCPs(savedConfig);
-    ctx.externalMCPs.push(...externalMCPList);
+    ctx.mcp.addAll(externalMCPList);
     // Mark startup complete — flushes queued output and restores console
     startup.ready();
     // Notify connected clients that photon list is now available
@@ -2823,14 +2961,9 @@ export async function startBeam(rawWorkingDir, port) {
                     // Remove MCPs — do all synchronous Map mutations first, then close async
                     const removedSdkClients = [];
                     for (const name of removed) {
-                        const idx = ctx.externalMCPs.findIndex((m) => m.name === name);
-                        if (idx !== -1)
-                            ctx.externalMCPs.splice(idx, 1);
-                        const sdkClient = ctx.externalMCPSDKClients.get(name);
+                        const { sdkClient } = ctx.mcp.removeByName(name);
                         if (sdkClient)
                             removedSdkClients.push({ name, client: sdkClient });
-                        ctx.externalMCPSDKClients.delete(name);
-                        ctx.externalMCPClients.delete(name);
                         logger.info(`🔌 Removed external MCP: ${name}`);
                     }
                     // Close SDK clients after all Maps are consistent
@@ -2849,7 +2982,7 @@ export async function startBeam(rawWorkingDir, port) {
                             mcpServers: Object.fromEntries(added.map((k) => [k, newServers[k]])),
                         };
                         const newMCPs = await loadExternalMCPs(addConfig);
-                        ctx.externalMCPs.push(...newMCPs);
+                        ctx.mcp.addAll(newMCPs);
                         for (const m of newMCPs) {
                             logger.info(`🔌 Added external MCP: ${m.name} (${m.connected ? m.methods.length + ' tools' : 'failed'})`);
                         }
@@ -2857,14 +2990,9 @@ export async function startBeam(rawWorkingDir, port) {
                     // Reconnect modified MCPs — synchronous cleanup first, then async reconnect
                     const modifiedSdkClients = [];
                     for (const name of modified) {
-                        const idx = ctx.externalMCPs.findIndex((m) => m.name === name);
-                        if (idx !== -1)
-                            ctx.externalMCPs.splice(idx, 1);
-                        const sdkClient = ctx.externalMCPSDKClients.get(name);
+                        const { sdkClient } = ctx.mcp.removeByName(name);
                         if (sdkClient)
                             modifiedSdkClients.push({ name, client: sdkClient });
-                        ctx.externalMCPSDKClients.delete(name);
-                        ctx.externalMCPClients.delete(name);
                     }
                     // Close old SDK clients
                     for (const { client } of modifiedSdkClients) {
@@ -2882,7 +3010,7 @@ export async function startBeam(rawWorkingDir, port) {
                             mcpServers: { [name]: newServers[name] },
                         };
                         const reconnected = await loadExternalMCPs(modConfig);
-                        ctx.externalMCPs.push(...reconnected);
+                        ctx.mcp.addAll(reconnected);
                         logger.info(`🔌 Reconnected external MCP: ${name}`);
                     }
                     // Update savedConfig
@@ -2912,18 +3040,7 @@ export async function startBeam(rawWorkingDir, port) {
 export async function stopBeam() {
     // Stop session cleanup timer
     stopSessionCleanup();
-    // Close all SDK clients gracefully
-    const closePromises = [];
-    for (const [, client] of ctx.externalMCPSDKClients) {
-        closePromises.push(client.close().catch(() => {
-            // Ignore close errors - process is exiting anyway
-        }));
-    }
-    // Wait for all clients to close (with timeout)
-    if (closePromises.length > 0) {
-        await withTimeout(Promise.all(closePromises), 1000, 'MCP client close timeout').catch(() => { }); // Timeout during shutdown is expected
-    }
-    ctx.externalMCPSDKClients.clear();
-    ctx.externalMCPClients.clear();
+    // Close every external MCP SDK client gracefully and clear the maps.
+    await ctx.mcp.closeAllSDKClients();
 }
 //# sourceMappingURL=beam.js.map