@portel/photon 1.16.0 → 1.17.0

package/dist/auto-ui/beam.js

@@ -8,6 +8,7 @@
 import * as http from 'http';
 import * as net from 'net';
 import * as fs from 'fs/promises';
+import { readText, readJSON as readJSONFile, writeText } from '../shared/io.js';
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, watch, } from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -97,14 +98,14 @@ import { MarketplaceManager } from '../marketplace-manager.js';
 import { subscribeChannel, reloadDaemonPhoton } from '../daemon/client.js';
 import { ensurePhotonEditorDeclaration, writePhotonEditorDeclaration, } from '../photon-editor-declarations.js';
 import { ensureDaemon } from '../daemon/manager.js';
-import { SchemaExtractor, } from '@portel/photon-core';
+import { SchemaExtractor } from '@portel/photon-core';
 import { generateServerCard } from '../server-card.js';
 import { handleStreamableHTTP, broadcastNotification, broadcastToBeam, } 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)
 import { loadConfig as loadConfigFromModule, saveConfig as saveConfigFromModule, migrateConfig as migrateConfigFromModule, getConfigFilePath as getConfigFilePathFromModule, } from './beam/config.js';
-import { extractClassMetadataFromSource as extractClassMetadataFromModule, applyMethodVisibility as applyMethodVisibilityFromModule, extractCspFromSource as extractCspFromModule, prettifyName as prettifyNameFromModule, prettifyToolName as prettifyToolNameFromModule, backfillEnvDefaults as backfillEnvDefaultsFromModule, } from './beam/class-metadata.js';
+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 { handleMarketplaceRoutes } from './beam/routes/api-marketplace.js';
@@ -119,8 +120,6 @@ const getConfigFilePath = getConfigFilePathFromModule;
 const externalMCPs = [];
 const externalMCPClients = new Map();
 const externalMCPSDKClients = new Map();
-// Delegate to extracted module
-const prettifyToolName = prettifyToolNameFromModule;
 // Delegates — external MCP management now in beam/external-mcp.ts
 const externalMCPState = { externalMCPs, externalMCPClients, externalMCPSDKClients };
 const loadExternalMCPs = (config) => loadExternalMCPsFromModule(config, externalMCPState);
@@ -485,18 +484,43 @@ export async function startBeam(rawWorkingDir, port) {
         logger.warn(`Asset repair check failed: ${getErrorMessage(error)}`);
     }
     // Discover all photons with namespace metadata (user photons + bundled photons)
-    const userPhotonListDetailed = await listPhotonFilesWithNamespace(workingDir);
-    // Detect name collisions to decide sidebar display names
+    const scannedPhotonList = await listPhotonFilesWithNamespace(workingDir);
+    // Deduplicate aliases that resolve to the same underlying file (for example,
+    // a marketplace photon and a local alias/symlink that both point at the same
+    // source). Beam should not show both copies in the sidebar.
+    const userPhotonListDetailed = [];
+    const seenPhotonKeys = new Set();
+    for (const photon of scannedPhotonList) {
+        let realPath = photon.filePath;
+        try {
+            realPath = realpathSync(photon.filePath);
+        }
+        catch {
+            // Fall back to the discovered path if realpath resolution fails.
+        }
+        const dedupeKey = `${photon.name}::${realPath}`;
+        if (seenPhotonKeys.has(dedupeKey))
+            continue;
+        seenPhotonKeys.add(dedupeKey);
+        userPhotonListDetailed.push(photon);
+    }
+    // Detect name collisions and generate friendly duplicate labels. We should
+    // never leak namespace/owner names into the sidebar just because there are
+    // multiple copies of a photon with the same short name.
     const nameOccurrences = new Map();
     for (const p of userPhotonListDetailed) {
         nameOccurrences.set(p.name, (nameOccurrences.get(p.name) || 0) + 1);
     }
-    // Build photon list: use qualifiedName when collision, short name when unique
-    // Also track resolved paths from namespace scan
+    // Build photon list with short names plus a numeric suffix for duplicates.
+    // Also track resolved paths from namespace scan.
     const namespacePaths = new Map(); // displayName → filePath
     const userPhotonList = [];
+    const duplicateIndex = new Map();
     for (const p of userPhotonListDetailed) {
-        const displayName = (nameOccurrences.get(p.name) || 0) > 1 ? p.qualifiedName : p.name;
+        const duplicateCount = nameOccurrences.get(p.name) || 0;
+        const nextIndex = (duplicateIndex.get(p.name) || 0) + 1;
+        duplicateIndex.set(p.name, nextIndex);
+        const displayName = duplicateCount > 1 ? `${p.name} (${nextIndex})` : p.name;
         userPhotonList.push(displayName);
         namespacePaths.set(displayName, p.filePath);
     }
@@ -527,9 +551,6 @@ 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);
-    // Counts updated after photon loading
-    let configuredCount = 0;
-    let unconfiguredCount = 0;
     // Check for placeholder defaults or localhost URLs (which need local services running)
     const isPlaceholderOrLocalDefault = (value) => {
         if (value.includes('<') || value.includes('your-'))
@@ -558,7 +579,7 @@ export async function startBeam(rawWorkingDir, port) {
         let source;
         let isInternal;
         try {
-            source = await fs.readFile(photonPath, 'utf-8');
+            source = await readText(photonPath);
             await ensurePhotonEditorDeclaration(photonPath, source, workingDir).catch(() => { });
         }
         catch {
@@ -634,7 +655,7 @@ export async function startBeam(rawWorkingDir, port) {
             photonMCPs.set(name, mcp);
             backfillEnvDefaults(instance, constructorParams);
             // Extract schema for UI — reuse source read from above
-            const schemaSource = source || (await fs.readFile(photonPath, 'utf-8'));
+            const schemaSource = source || (await readText(photonPath));
             const metadata = extractor.extractAllFromSource(schemaSource);
             const schemas = metadata.tools;
             const templates = metadata.templates;
@@ -652,8 +673,6 @@ export async function startBeam(rawWorkingDir, port) {
             // If loader didn't resolve UI assets but source has @ui tags,
             // extract them from source to populate linkedUi for sidebar
             if (uiAssets.length === 0 && schemaSource) {
-                const uiTagRegex = /^\s*\*\s*@ui\s+(\S+)(?:\s+(\S+))?/gm;
-                let uiMatch;
                 const classUiMatch = schemaSource.match(/^\s*\*\s*@ui\s+(\S+)\s+(\.\/\S+)/m);
                 if (classUiMatch) {
                     // Class-level @ui tag with file path: @ui dashboard ./ui/dashboard.html
@@ -777,8 +796,10 @@ export async function startBeam(rawWorkingDir, port) {
             catch {
                 // No install metadata - that's fine
             }
-            const isStateful = schemaSource ? /@stateful\b/.test(schemaSource) : false;
-            const authMatch = schemaSource?.match(/@auth\b(?:\s+(\S+))?/i);
+            // Extract class-level JSDoc block to avoid matching @tags inside template literals
+            const classDocblock = schemaSource?.match(/\/\*\*[\s\S]*?\*\/\s*(?:export\s+)?(?:default\s+)?class\b/)?.[0] ?? '';
+            const isStateful = classDocblock ? /@stateful\b/.test(classDocblock) : false;
+            const authMatch = classDocblock?.match(/@auth\b(?:\s+(\S+))?/i);
             const authValue = authMatch ? authMatch[1]?.trim() || 'required' : undefined;
             return {
                 id: generatePhotonId(photonPath),
@@ -844,19 +865,26 @@ export async function startBeam(rawWorkingDir, port) {
             uiPath = asset.resolvedPath;
         }
         else {
-            // Prefer .photon.html (declarative mode) over .html (full control)
+            // Prefer .photon.html, then .photon.md, fall back to .html
             const photonHtmlPath = path.join(photonDir, photonName, 'ui', `${uiId}.photon.html`);
+            const photonMdPath = path.join(photonDir, photonName, 'ui', `${uiId}.photon.md`);
             try {
                 await fs.access(photonHtmlPath);
                 uiPath = photonHtmlPath;
             }
             catch {
-                uiPath = path.join(photonDir, photonName, 'ui', `${uiId}.html`);
+                try {
+                    await fs.access(photonMdPath);
+                    uiPath = photonMdPath;
+                }
+                catch {
+                    uiPath = path.join(photonDir, photonName, 'ui', `${uiId}.html`);
+                }
             }
         }
-        const isPhotonTemplate = uiPath.endsWith('.photon.html');
+        const isPhotonTemplate = uiPath.endsWith('.photon.html') || uiPath.endsWith('.photon.md');
         try {
-            const content = await fs.readFile(uiPath, 'utf-8');
+            const content = await readText(uiPath);
             return { content, isPhotonTemplate };
         }
         catch {
@@ -868,7 +896,7 @@ export async function startBeam(rawWorkingDir, port) {
             const formatName = uiId.slice('format-'.length);
             const formatPath = path.join(photonDir, photonName, 'assets', 'formats', `${formatName}.html`);
             try {
-                const content = await fs.readFile(formatPath, 'utf-8');
+                const content = await readText(formatPath);
                 return { content, isPhotonTemplate: false };
             }
             catch {
@@ -1019,7 +1047,12 @@ export async function startBeam(rawWorkingDir, port) {
                         return configurePhotonViaMCP(photonName, config, photons, photonMCPs, loader, savedConfig, workingDir, activeLoads);
                     },
                     reloadPhoton: async (photonName) => {
-                        return reloadPhotonViaMCP(photonName, photons, photonMCPs, loader, savedConfig, broadcastPhotonChange, activeLoads);
+                        return reloadPhotonViaMCP(photonName, photons, photonMCPs, loader, savedConfig, broadcastPhotonChange, activeLoads, (name, path, isStateful) => {
+                            if (isStateful) {
+                                subscribeStatefulPhoton(name).catch(() => { });
+                                reloadDaemonPhoton(name, path, workingDir).catch(() => { });
+                            }
+                        });
                     },
                     removePhoton: async (photonName) => {
                         return removePhotonViaMCP(photonName, photons, photonMCPs, savedConfig, broadcastPhotonChange, workingDir);
@@ -1190,7 +1223,7 @@ export async function startBeam(rawWorkingDir, port) {
             if (url.pathname === '/beam.bundle.js') {
                 try {
                     const bundlePath = path.join(__dirname, '../../dist/beam.bundle.js');
-                    const content = await fs.readFile(bundlePath, 'utf-8');
+                    const content = await readText(bundlePath);
                     res.writeHead(200, {
                         'Content-Type': 'text/javascript',
                         'Cache-Control': 'no-cache',
@@ -1199,7 +1232,7 @@ export async function startBeam(rawWorkingDir, port) {
                 }
                 catch {
                     res.writeHead(404);
-                    res.end('Bundle not found. Run npm run build:beam first.');
+                    res.end('Bundle not found. Run the beam build script first.');
                 }
                 return;
             }
@@ -1207,7 +1240,7 @@ export async function startBeam(rawWorkingDir, port) {
             if (url.pathname === '/beam-form.bundle.js') {
                 try {
                     const formBundlePath = path.join(__dirname, '../../dist/beam-form.bundle.js');
-                    const content = await fs.readFile(formBundlePath, 'utf-8');
+                    const content = await readText(formBundlePath);
                     res.writeHead(200, {
                         'Content-Type': 'text/javascript',
                         'Cache-Control': 'no-cache',
@@ -1216,14 +1249,14 @@ export async function startBeam(rawWorkingDir, port) {
                 }
                 catch {
                     res.writeHead(404);
-                    res.end('Form bundle not found. Run npm run build:beam first.');
+                    res.end('Form bundle not found. Run the beam build script first.');
                 }
                 return;
             }
             if (url.pathname === '/beam-ts-worker.js') {
                 try {
                     const workerPath = path.join(__dirname, '../../dist/beam-ts-worker.js');
-                    const content = await fs.readFile(workerPath, 'utf-8');
+                    const content = await readText(workerPath);
                     res.writeHead(200, {
                         'Content-Type': 'text/javascript',
                         'Cache-Control': 'no-cache',
@@ -1232,7 +1265,7 @@ export async function startBeam(rawWorkingDir, port) {
                 }
                 catch {
                     res.writeHead(404);
-                    res.end('TS worker not found. Run npm run build:beam first.');
+                    res.end('TS worker not found. Run the beam build script first.');
                 }
                 return;
             }
@@ -1696,7 +1729,7 @@ export async function startBeam(rawWorkingDir, port) {
                             params[k] = v;
                     }
                     const pureViewPath = path.join(__dirname, 'frontend/pure-view.html');
-                    let html = await fs.readFile(pureViewPath, 'utf-8');
+                    let html = await readText(pureViewPath);
                     // Replace placeholders
                     const argsJson = escapeHtml(JSON.stringify(params));
                     html = html
@@ -1720,7 +1753,7 @@ export async function startBeam(rawWorkingDir, port) {
             if (url.pathname === '/' || !url.pathname.startsWith('/api')) {
                 try {
                     const indexPath = path.join(__dirname, 'frontend/index.html');
-                    let content = await fs.readFile(indexPath, 'utf-8');
+                    let content = await readText(indexPath);
                     // Inject shell integration flag so frontend can strip CLI prefix
                     if (_shellIntegrationInstalled) {
                         content = content.replace('</head>', '<script>window.__PHOTON_SHELL_INIT=true</script></head>');
@@ -1905,14 +1938,14 @@ export async function startBeam(rawWorkingDir, port) {
                     // Auto-scaffold empty photon files with a starter template
                     if (isNewPhoton) {
                         try {
-                            const rawContent = await fs.readFile(photonPath, 'utf-8');
+                            const rawContent = await readText(photonPath);
                             if (rawContent.trim().length === 0) {
                                 const className = photonName
                                     .split(/[-_]/)
                                     .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
                                     .join('');
                                 const scaffold = `/**\n * ${className} Photon\n */\n\nexport default class ${className} {\n  /**\n   * Example tool\n   * @param message Message to echo\n   */\n  async echo(params: { message: string }) {\n    return \`Echo: \${params.message}\`;\n  }\n}\n`;
-                                await fs.writeFile(photonPath, scaffold, 'utf-8');
+                                await writeText(photonPath, scaffold);
                                 logger.info(`📝 Scaffolded empty file: ${photonName}.photon.ts`);
                                 // The write triggers another watcher event which will load the scaffolded photon
                                 return;
@@ -1927,7 +1960,7 @@ export async function startBeam(rawWorkingDir, port) {
                         const extractor = new SchemaExtractor();
                         let constructorParams = [];
                         try {
-                            const source = await fs.readFile(photonPath, 'utf-8');
+                            const source = await readText(photonPath);
                             await writePhotonEditorDeclaration(photonPath, source, workingDir).catch(() => { });
                             const params = extractor.extractConstructorParams(source);
                             constructorParams = params
@@ -1975,7 +2008,7 @@ export async function startBeam(rawWorkingDir, port) {
                         photonMCPs.set(photonName, mcp);
                         // Re-extract schema - use extractAllFromSource to get both tools and templates
                         const extractor = new SchemaExtractor();
-                        const reloadSource = await fs.readFile(photonPath, 'utf-8');
+                        const reloadSource = await readText(photonPath);
                         await writePhotonEditorDeclaration(photonPath, reloadSource, workingDir).catch(() => { });
                         const reloadMetadata = extractor.extractAllFromSource(reloadSource);
                         const schemas = reloadMetadata.tools;
@@ -2153,7 +2186,7 @@ export async function startBeam(rawWorkingDir, port) {
                             const extractor = new SchemaExtractor();
                             let constructorParams = [];
                             try {
-                                const source = await fs.readFile(photonPath, 'utf-8');
+                                const source = await readText(photonPath);
                                 const params = extractor.extractConstructorParams(source);
                                 constructorParams = params
                                     .filter((p) => p.isPrimitive)
@@ -2340,18 +2373,9 @@ export async function startBeam(rawWorkingDir, port) {
             }
         }
     }
-    configuredCount = photons.filter((p) => p.configured).length;
-    unconfiguredCount = photons.filter((p) => !p.configured).length;
     // Load external MCPs from config
     const externalMCPList = await loadExternalMCPs(savedConfig);
     externalMCPs.push(...externalMCPList);
-    const connectedMCPs = externalMCPList.filter((m) => m.connected).length;
-    const failedMCPs = externalMCPList.length - connectedMCPs;
-    const photonStatus = unconfiguredCount > 0
-        ? `${configuredCount} ready, ${unconfiguredCount} need setup`
-        : `${configuredCount} photon${configuredCount !== 1 ? 's' : ''} ready`;
-    const mcpStatus = externalMCPList.length > 0 ? `, ${connectedMCPs}/${externalMCPList.length} MCPs` : '';
-    const url = `http://localhost:${process.env.BEAM_PORT || port}`;
     // Mark startup complete — flushes queued output and restores console
     startup.ready();
     // Notify connected clients that photon list is now available
@@ -2376,8 +2400,7 @@ export async function startBeam(rawWorkingDir, port) {
                             const instName = instanceName || 'default';
                             const stateFile = path.join(workingDir, 'state', photonName, `${instName}.json`);
                             try {
-                                const json = await fs.readFile(stateFile, 'utf-8');
-                                const state = JSON.parse(json);
+                                const state = await readJSONFile(stateFile);
                                 for (const [key, value] of Object.entries(state)) {
                                     const target = mcp.instance[key];
                                     if (target && typeof target.splice === 'function' && Array.isArray(value)) {
@@ -2619,8 +2642,8 @@ export async function startBeam(rawWorkingDir, port) {
                     configDebounce = null;
                     let newConfig;
                     try {
-                        const data = await fs.readFile(configFile, 'utf-8');
-                        newConfig = migrateConfig(JSON.parse(data));
+                        const data = await readJSONFile(configFile);
+                        newConfig = migrateConfig(data);
                     }
                     catch (err) {
                         logger.warn(`⚠️ Failed to parse config.json: ${err instanceof Error ? err.message : String(err)}`);
@@ -2654,7 +2677,7 @@ export async function startBeam(rawWorkingDir, port) {
                         logger.info(`🔌 Removed external MCP: ${name}`);
                     }
                     // Close SDK clients after all Maps are consistent
-                    for (const { name, client } of removedSdkClients) {
+                    for (const { name: _name, client } of removedSdkClients) {
                         try {
                             await client.close();
                         }