@portel/photon 1.28.2 → 1.31.0

package/dist/auto-ui/beam.js

@@ -102,7 +102,7 @@ import { ensureDaemon } from '../daemon/manager.js';
 import { SchemaExtractor } from '@portel/photon-core';
 import { generateServerCard } from '../server-card.js';
 import { resolveUIAssetPath, readUIContent } from './ui-resolver.js';
-import { handleStreamableHTTP, broadcastNotification, broadcastToBeam, stopSessionCleanup, } from './streamable-http-transport.js';
+import { handleStreamableHTTP, broadcastNotification, broadcastToBeam, stopSessionCleanup, attachLoaderForResourceUpdates, } from './streamable-http-transport.js';
 import { getBundledPhotonPath, BEAM_BUNDLED_PHOTONS } from '../shared-utils.js';
 // BUNDLED_PHOTONS and getBundledPhotonPath are imported from shared-utils.js
 // Extracted modules (Phase 5)
@@ -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,
         };
     }
 }
@@ -598,6 +607,9 @@ export async function startBeam(rawWorkingDir, port) {
     // Beam handles config errors gracefully via UI forms, but we still want to see actual errors
     const errorOnlyLogger = createLogger({ level: 'error' });
     const loader = new PhotonLoader(false, errorOnlyLogger, workingDir);
+    // Bridge `this.notifyResourceUpdated(uri)` from photon authors into the
+    // streamable-HTTP subscription registry so SSE clients get fanout.
+    attachLoaderForResourceUpdates(loader);
     // Check for placeholder defaults or localhost URLs (which need local services running)
     const isPlaceholderOrLocalDefault = (value) => {
         if (value.includes('<') || value.includes('your-'))
@@ -750,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 });
                         }
                     });
                 }
@@ -833,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) {
@@ -934,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 = {
@@ -1194,54 +1209,85 @@ export async function startBeam(rawWorkingDir, port) {
                     res.end('Photon not found');
                     return;
                 }
-                // Resolve asset path using the same convention as Photon.assets():
-                // preferred {photonDir}/{photonBaseName}/{assetPath}, legacy fallback
-                // {photonDir}/{photonBaseName}/assets/{assetPath}.
+                // Dual-layout asset resolution (v1.29 Track E):
+                //   1. {photonDir}/{photonBaseName}/assets/{assetPath}  — canonical
+                //   2. {photonDir}/{photonBaseName}/{assetPath}         — legacy
+                // The new convention wins; legacy only fires when nothing matches
+                // under assets/ (preserves byte-compat for fixtures without an
+                // assets/ wrapper).
                 const realPath = realpathSync(photon.path);
                 const photonDir = path.dirname(realPath);
                 const baseName = path.basename(realPath).replace(/\.photon\.(ts|js)$/, '');
-                const assetsRoot = path.join(photonDir, baseName);
-                const legacyAssetsRoot = path.join(assetsRoot, 'assets');
-                const activeRoot = existsSync(assetsRoot) ? assetsRoot : legacyAssetsRoot;
-                const fullPath = path.join(activeRoot, assetPath);
-                // Security: ensure resolved path is within the assets directory
-                if (!fullPath.startsWith(activeRoot)) {
-                    res.writeHead(403);
-                    res.end('Forbidden');
-                    return;
-                }
-                try {
-                    const data = await fs.readFile(fullPath);
-                    const ext = path.extname(fullPath).toLowerCase();
-                    const mimeTypes = {
-                        '.png': 'image/png',
-                        '.jpg': 'image/jpeg',
-                        '.jpeg': 'image/jpeg',
-                        '.gif': 'image/gif',
-                        '.svg': 'image/svg+xml',
-                        '.webp': 'image/webp',
-                        '.ico': 'image/x-icon',
-                        '.mp4': 'video/mp4',
-                        '.webm': 'video/webm',
-                        '.pdf': 'application/pdf',
-                        '.woff2': 'font/woff2',
-                        '.woff': 'font/woff',
-                        '.ttf': 'font/ttf',
-                        '.css': 'text/css',
-                        '.js': 'text/javascript',
-                        '.json': 'application/json',
-                        '.txt': 'text/plain',
-                    };
-                    res.writeHead(200, {
-                        'Content-Type': mimeTypes[ext] || 'application/octet-stream',
-                        'Cache-Control': 'public, max-age=3600',
-                    });
-                    res.end(data);
-                }
-                catch {
+                const legacyRoot = path.join(photonDir, baseName);
+                const canonicalRoot = path.join(legacyRoot, 'assets');
+                const candidateRoots = [canonicalRoot, legacyRoot];
+                const tryRoots = async (subPath) => {
+                    for (const root of candidateRoots) {
+                        const candidate = path.join(root, subPath);
+                        const rootWithSep = root.endsWith(path.sep) ? root : root + path.sep;
+                        if (!candidate.startsWith(rootWithSep) && candidate !== root) {
+                            continue;
+                        }
+                        try {
+                            const stat = await fs.stat(candidate);
+                            if (stat.isDirectory()) {
+                                // Directory-style serve: if the dir contains index.html,
+                                // serve it. Otherwise fall through to the next root.
+                                const indexCandidate = path.join(candidate, 'index.html');
+                                try {
+                                    const data = await fs.readFile(indexCandidate);
+                                    return { data, resolved: indexCandidate };
+                                }
+                                catch {
+                                    continue;
+                                }
+                            }
+                            const data = await fs.readFile(candidate);
+                            return { data, resolved: candidate };
+                        }
+                        catch {
+                            continue;
+                        }
+                    }
+                    return null;
+                };
+                const found = await tryRoots(assetPath);
+                if (!found) {
                     res.writeHead(404);
                     res.end('Asset not found');
+                    return;
                 }
+                const ext = path.extname(found.resolved).toLowerCase();
+                const mimeTypes = {
+                    '.html': 'text/html; charset=utf-8',
+                    '.png': 'image/png',
+                    '.jpg': 'image/jpeg',
+                    '.jpeg': 'image/jpeg',
+                    '.gif': 'image/gif',
+                    '.svg': 'image/svg+xml',
+                    '.webp': 'image/webp',
+                    '.ico': 'image/x-icon',
+                    '.mp4': 'video/mp4',
+                    '.webm': 'video/webm',
+                    '.pdf': 'application/pdf',
+                    '.woff2': 'font/woff2',
+                    '.woff': 'font/woff',
+                    '.ttf': 'font/ttf',
+                    '.css': 'text/css',
+                    '.js': 'text/javascript',
+                    '.mjs': 'text/javascript',
+                    '.json': 'application/json',
+                    '.txt': 'text/plain',
+                    '.wasm': 'application/wasm',
+                };
+                res.writeHead(200, {
+                    'Content-Type': mimeTypes[ext] || 'application/octet-stream',
+                    'Cache-Control': 'public, max-age=3600',
+                    // Track D2: CORP same-origin keeps assets fetchable from a
+                    // standalone parent page that asserts COEP `require-corp`.
+                    'Cross-Origin-Resource-Policy': 'same-origin',
+                });
+                res.end(found.data);
                 return;
             }
             // ══════════════════════════════════════════════════════════════════════════
@@ -1353,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);
@@ -1840,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 {
@@ -1877,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) => {
@@ -2135,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);
@@ -2339,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',
@@ -2499,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
@@ -2789,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
@@ -2815,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'})`);
                         }
@@ -2823,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) {
@@ -2848,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
@@ -2878,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