@portel/photon 1.4.1 → 1.6.0

package/dist/cli.js

@@ -9,15 +9,305 @@ import * as path from 'path';
 import * as fs from 'fs/promises';
 import { existsSync } from 'fs';
 import * as os from 'os';
-import * as readline from 'readline';
+import * as net from 'net';
 import { PhotonServer } from './server.js';
 import { FileWatcher } from './watcher.js';
-import { resolvePhotonPath, listPhotonMCPs, ensureWorkingDir, DEFAULT_WORKING_DIR } from './path-resolver.js';
+import { resolvePhotonPath, listPhotonMCPs, ensureWorkingDir, DEFAULT_WORKING_DIR, } from './path-resolver.js';
 import { SchemaExtractor } from '@portel/photon-core';
 import { createRequire } from 'module';
 import { fileURLToPath } from 'url';
 const require = createRequire(import.meta.url);
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+import { getBundledPhotonPath, DEFAULT_BUNDLED_PHOTONS } from './shared-utils.js';
+import { PHOTON_VERSION } from './version.js';
+import { toEnvVarName } from './shared/config-docs.js';
+import { runTask } from './shared/task-runner.js';
+import { normalizeLogLevel, logger } from './shared/logger.js';
+import { printHeader, printInfo, printWarning, printError, printSuccess } from './cli-formatter.js';
+import { handleError, getErrorMessage, ExitCode, exitWithError, } from './shared/error-handler.js';
+import { validateOrThrow, inRange, isPositive, isInteger } from './shared/validation.js';
+import { createReadline, promptWait } from './shared/cli-utils.js';
+import { registerMarketplaceCommands } from './cli/commands/marketplace.js';
+import { registerInfoCommand } from './cli/commands/info.js';
+import { registerPackageCommands } from './cli/commands/package.js';
+import { registerPackageAppCommand } from './cli/commands/package-app.js';
+// ══════════════════════════════════════════════════════════════════════════════
+// BUNDLED PHOTONS
+// ══════════════════════════════════════════════════════════════════════════════
+/** Bundled photon names that ship with the runtime */
+// BUNDLED_PHOTONS and getBundledPhotonPath are imported from shared-utils.js
+/**
+ * Parse extended photon name format
+ *
+ * Supports:
+ * - "rss-feed" → { name: "rss-feed" }
+ * - "alice/custom-photons:rss-feed" → { name: "rss-feed", marketplaceSource: "alice/custom-photons" }
+ *
+ * Rule: colon splits only when left side contains `/` (a marketplace source)
+ * and right side is a simple name (no `/`).
+ */
+export function parsePhotonSpec(spec) {
+    const colonIndex = spec.indexOf(':');
+    if (colonIndex > 0) {
+        const left = spec.slice(0, colonIndex);
+        const right = spec.slice(colonIndex + 1);
+        // Left must contain `/` (marketplace source) and right must be a simple name
+        if (left.includes('/') && right && !right.includes('/')) {
+            return { name: right, marketplaceSource: left };
+        }
+    }
+    return { name: spec };
+}
+/**
+ * Resolve photon path - checks bundled first, then user directory
+ */
+async function resolvePhotonPathWithBundled(name, workingDir) {
+    // Check bundled photons first
+    const bundledPath = getBundledPhotonPath(name, __dirname);
+    if (bundledPath) {
+        return bundledPath;
+    }
+    // Fall back to user photons
+    return resolvePhotonPath(name, workingDir);
+}
+// ══════════════════════════════════════════════════════════════════════════════
+// PORT UTILITIES
+// ══════════════════════════════════════════════════════════════════════════════
+/**
+ * Check if a port is available
+ */
+function isPortAvailable(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once('error', () => resolve(false));
+        server.once('listening', () => {
+            server.close();
+            resolve(true);
+        });
+        // Listen on all interfaces (same as http.createServer default)
+        server.listen(port);
+    });
+}
+function getLogOptionsFromCommand(command) {
+    const root = command?.parent?.opts?.() ?? program.opts();
+    try {
+        const level = normalizeLogLevel(root.logLevel);
+        return {
+            level,
+            json: Boolean(root.jsonLogs),
+        };
+    }
+    catch (error) {
+        handleError(error, { exitOnError: true });
+        throw error; // TypeScript doesn't know handleError exits
+    }
+}
+/**
+ * Find an available port starting from the given port
+ */
+async function findAvailablePort(startPort, maxAttempts = 10) {
+    // Validate port range
+    validateOrThrow(startPort, [
+        inRange('start port', 1, 65535),
+        isInteger('start port'),
+        isPositive('start port'),
+    ]);
+    for (let i = 0; i < maxAttempts; i++) {
+        const port = startPort + i;
+        if (port > 65535) {
+            throw new Error(`Port ${port} exceeds maximum port number (65535)`);
+        }
+        if (await isPortAvailable(port)) {
+            return port;
+        }
+    }
+    throw new Error(`No available port found between ${startPort} and ${startPort + maxAttempts - 1}`);
+}
+function cliHeading(title) {
+    console.log('');
+    printHeader(title);
+}
+function cliListItem(text) {
+    printInfo(`  ${text}`);
+}
+function cliSpacer() {
+    console.log('');
+}
+function cliHint(message) {
+    printWarning(message);
+}
+// ══════════════════════════════════════════════════════════════════════════════
+// ELICITATION HANDLERS
+// ══════════════════════════════════════════════════════════════════════════════
+/**
+ * Handle form-based elicitation (MCP-aligned)
+ * Renders a multi-field form in CLI using readline
+ */
+async function handleFormElicitation(ask) {
+    cliHeading(`📝 ${ask.message}`);
+    cliHint('Press Enter to accept defaults. Fields marked * are required.');
+    cliSpacer();
+    const rl = createReadline();
+    const question = (prompt) => {
+        return new Promise((resolve) => {
+            rl.question(prompt, (answer) => resolve(answer));
+        });
+    };
+    const result = {};
+    const required = ask.schema.required || [];
+    for (const [key, prop] of Object.entries(ask.schema.properties)) {
+        const title = prop.title || key;
+        const isRequired = required.includes(key);
+        const reqMark = isRequired ? '*' : '';
+        const defaultVal = prop.default !== undefined ? ` [${prop.default}]` : '';
+        let value;
+        // Handle different property types
+        if (prop.type === 'boolean') {
+            const answer = await question(`${title}${reqMark} (y/n)${defaultVal}: `);
+            if (answer === '' && prop.default !== undefined) {
+                value = prop.default;
+            }
+            else {
+                value = answer.toLowerCase().startsWith('y');
+            }
+        }
+        else if (prop.enum || prop.oneOf) {
+            // Single select
+            const options = prop.oneOf
+                ? prop.oneOf.map((o) => ({ value: o.const, label: o.title }))
+                : prop.enum.map((e) => ({ value: e, label: e }));
+            printInfo(`${title}${reqMark}:`);
+            options.forEach((opt, i) => {
+                const isDefault = opt.value === prop.default ? ' (default)' : '';
+                cliListItem(`${i + 1}. ${opt.label}${isDefault}`);
+            });
+            const answer = await question(`Choose (1-${options.length})${defaultVal}: `);
+            const idx = parseInt(answer) - 1;
+            if (idx >= 0 && idx < options.length) {
+                value = options[idx].value;
+            }
+            else if (answer === '' && prop.default !== undefined) {
+                value = prop.default;
+            }
+            else {
+                value = options[0].value;
+            }
+        }
+        else if (prop.type === 'array') {
+            // Multi-select
+            const items = prop.items?.anyOf || prop.items?.enum?.map((e) => ({ const: e, title: e }));
+            if (items) {
+                printInfo(`${title}${reqMark} (comma-separated numbers):`);
+                items.forEach((item, i) => {
+                    const label = item.title || item.const || item;
+                    cliListItem(`${i + 1}. ${label}`);
+                });
+                const answer = await question('Choose: ');
+                const indices = answer.split(',').map((s) => parseInt(s.trim()) - 1);
+                value = indices
+                    .filter((idx) => idx >= 0 && idx < items.length)
+                    .map((idx) => items[idx].const || items[idx]);
+                if (value.length === 0 && prop.default) {
+                    value = prop.default;
+                }
+            }
+            else {
+                value = prop.default || [];
+            }
+        }
+        else if (prop.type === 'number' || prop.type === 'integer') {
+            const answer = await question(`${title}${reqMark}${defaultVal}: `);
+            if (answer === '' && prop.default !== undefined) {
+                value = prop.default;
+            }
+            else {
+                value = prop.type === 'integer' ? parseInt(answer) : parseFloat(answer);
+                if (isNaN(value))
+                    value = prop.default ?? 0;
+            }
+        }
+        else {
+            // String or default
+            const format = prop.format ? ` (${prop.format})` : '';
+            const answer = await question(`${title}${reqMark}${format}${defaultVal}: `);
+            value = answer || prop.default || '';
+        }
+        result[key] = value;
+        cliSpacer();
+    }
+    rl.close();
+    cliSpacer();
+    return { action: 'accept', content: result };
+}
+/**
+ * Handle URL-based elicitation (OAuth flows)
+ * Opens URL in browser and waits for user confirmation
+ */
+async function handleUrlElicitation(ask) {
+    cliHeading(`🔗 ${ask.message}`);
+    printInfo(`URL: ${ask.url}`);
+    cliHint('Opening your default browser...');
+    cliSpacer();
+    // Open URL in default browser
+    const platform = process.platform;
+    const openCommand = platform === 'darwin' ? 'open' : platform === 'win32' ? 'start' : 'xdg-open';
+    try {
+        const { exec } = await import('child_process');
+        exec(`${openCommand} "${ask.url}"`);
+    }
+    catch (error) {
+        cliHint('Please open the URL manually in your browser.');
+    }
+    const shouldContinue = await promptWait('Press Enter when done', true);
+    return { action: shouldContinue ? 'accept' : 'cancel' };
+}
+/**
+ * Handle select elicitation with options
+ */
+async function handleSelectElicitation(ask) {
+    cliHeading(ask.message);
+    const options = ask.options.map((opt) => typeof opt === 'string' ? { value: opt, label: opt } : opt);
+    options.forEach((opt, i) => {
+        const isDefault = ask.default === opt.value || (Array.isArray(ask.default) && ask.default.includes(opt.value));
+        const defaultMark = isDefault ? ' ✓' : '';
+        const desc = opt.description ? ` - ${opt.description}` : '';
+        cliListItem(`${i + 1}. ${opt.label}${desc}${defaultMark}`);
+    });
+    cliSpacer();
+    const rl = createReadline();
+    const prompt = ask.multi
+        ? `Choose (comma-separated, 1-${options.length}): `
+        : `Choose (1-${options.length}): `;
+    return new Promise((resolve) => {
+        rl.question(prompt, (answer) => {
+            rl.close();
+            if (ask.multi) {
+                if (answer.trim() === '') {
+                    resolve(Array.isArray(ask.default) ? ask.default : []);
+                }
+                else {
+                    const indices = answer.split(',').map((s) => parseInt(s.trim()) - 1);
+                    const values = indices
+                        .filter((idx) => idx >= 0 && idx < options.length)
+                        .map((idx) => options[idx].value);
+                    resolve(values);
+                }
+            }
+            else {
+                const idx = parseInt(answer) - 1;
+                if (idx >= 0 && idx < options.length) {
+                    resolve(options[idx].value);
+                }
+                else if (answer.trim() === '' && ask.default) {
+                    resolve(ask.default);
+                }
+                else {
+                    resolve(options[0].value);
+                }
+            }
+        });
+    });
+}
 /**
  * Extract constructor parameters from a Photon MCP file
  */
@@ -28,21 +318,10 @@ async function extractConstructorParams(filePath) {
         return extractor.extractConstructorParams(source);
     }
     catch (error) {
-        console.error(`Failed to extract constructor params: ${error.message}`);
+        printError(`Failed to extract constructor params: ${getErrorMessage(error)}`);
         return [];
     }
 }
-/**
- * Convert MCP name and parameter name to environment variable name
- */
-function toEnvVarName(mcpName, paramName) {
-    const mcpPrefix = mcpName.toUpperCase().replace(/-/g, '_');
-    const paramSuffix = paramName
-        .replace(/([A-Z])/g, '_$1')
-        .toUpperCase()
-        .replace(/^_/, '');
-    return `${mcpPrefix}_${paramSuffix}`;
-}
 /**
  * Ensure .gitignore includes marketplace template directory
  */
@@ -67,7 +346,7 @@ async function ensureGitignore(workingDir) {
     }
     catch (error) {
         // Non-fatal - just warn
-        console.error(`   ⚠ Could not update .gitignore: ${error.message}`);
+        console.error(`   ⚠ Could not update .gitignore: ${getErrorMessage(error)}`);
     }
 }
 /**
@@ -77,21 +356,23 @@ async function performMarketplaceSync(dirPath, options) {
     const resolvedPath = path.resolve(dirPath);
     const isDefaultDir = resolvedPath === DEFAULT_WORKING_DIR;
     if (!existsSync(resolvedPath)) {
-        console.error(`❌ Directory not found: ${resolvedPath}`);
-        process.exit(1);
+        exitWithError(`Directory not found: ${resolvedPath}`, {
+            exitCode: ExitCode.NOT_FOUND,
+            suggestion: 'Check the path and ensure the directory exists',
+        });
     }
     // Scan for .photon.ts files
     console.error('📦 Scanning for .photon.ts files...');
     const files = await fs.readdir(resolvedPath);
-    let photonFiles = files.filter(f => f.endsWith('.photon.ts'));
+    let photonFiles = files.filter((f) => f.endsWith('.photon.ts'));
     // Filter out installed photons if requested (for ~/.photon)
     if (options.filterInstalled && isDefaultDir) {
         const { readLocalMetadata } = await import('./marketplace-manager.js');
         const metadata = await readLocalMetadata();
         // Metadata keys may include .photon.ts extension
-        const installedNames = new Set(Object.keys(metadata.photons || {}).map(k => k.replace(/\.photon\.ts$/, '')));
+        const installedNames = new Set(Object.keys(metadata.photons || {}).map((k) => k.replace(/\.photon\.ts$/, '')));
         const originalCount = photonFiles.length;
-        photonFiles = photonFiles.filter(f => {
+        photonFiles = photonFiles.filter((f) => {
             const name = f.replace(/\.photon\.ts$/, '');
             return !installedNames.has(name);
         });
@@ -100,8 +381,11 @@ async function performMarketplaceSync(dirPath, options) {
         }
     }
     if (photonFiles.length === 0) {
-        console.error(`❌ No .photon.ts files found in ${resolvedPath}`);
-        process.exit(1);
+        exitWithError(`No .photon.ts files found`, {
+            exitCode: ExitCode.NOT_FOUND,
+            searchedIn: resolvedPath,
+            suggestion: "Create a .photon.ts file or use 'photon maker new' to generate one",
+        });
     }
     console.error(`   Found ${photonFiles.length} photons\n`);
     // Initialize template manager
@@ -136,7 +420,10 @@ async function performMarketplaceSync(dirPath, options) {
             homepage: metadata.homepage,
             source: `../${file}`,
             hash,
-            tools: metadata.tools?.map(t => t.name),
+            tools: metadata.tools?.map((t) => t.name),
+            assets: metadata.assets,
+            photonType: metadata.photonType,
+            features: metadata.features,
         });
         // Generate individual photon documentation
         const photonMarkdown = await templateMgr.renderTemplate('photon.md', metadata);
@@ -146,18 +433,31 @@ async function performMarketplaceSync(dirPath, options) {
     // Create manifest
     console.error('\n📋 Updating manifest...');
     const baseName = path.basename(resolvedPath);
+    const marketplaceDir = path.join(resolvedPath, '.marketplace');
+    await fs.mkdir(marketplaceDir, { recursive: true });
+    const manifestPath = path.join(marketplaceDir, 'photons.json');
+    // Read existing manifest to preserve owner if not explicitly provided
+    let existingOwner;
+    if (existsSync(manifestPath) && !options.owner) {
+        try {
+            const existingManifest = JSON.parse(await fs.readFile(manifestPath, 'utf-8'));
+            existingOwner = existingManifest.owner;
+        }
+        catch {
+            // Ignore parse errors
+        }
+    }
     const manifest = {
         name: options.name || baseName,
-        version: '1.0.0',
+        version: PHOTON_VERSION,
         description: options.description || undefined,
-        owner: options.owner ? {
-            name: options.owner,
-        } : undefined,
+        owner: options.owner
+            ? {
+                name: options.owner,
+            }
+            : existingOwner,
         photons,
     };
-    const marketplaceDir = path.join(resolvedPath, '.marketplace');
-    await fs.mkdir(marketplaceDir, { recursive: true });
-    const manifestPath = path.join(marketplaceDir, 'photons.json');
     await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2), 'utf-8');
     console.error('   ✓ .marketplace/photons.json');
     // Sync README with generated content
@@ -169,12 +469,14 @@ async function performMarketplaceSync(dirPath, options) {
     const readmeContent = await templateMgr.renderTemplate('readme.md', {
         marketplaceName: manifest.name,
         marketplaceDescription: manifest.description || '',
-        photons: photons.map(p => ({
+        photons: photons.map((p) => ({
             name: p.name,
             description: p.description,
             version: p.version,
             license: p.license,
             tools: p.tools || [],
+            photonType: p.photonType || 'api',
+            features: p.features || [],
         })),
     });
     const isUpdate = await syncer.sync(readmeContent);
@@ -206,8 +508,11 @@ async function performMarketplaceInit(dirPath, options) {
     // Check if it's a git repository
     const gitDir = path.join(absolutePath, '.git');
     if (!existsSync(gitDir)) {
-        console.error('⚠️  Not a git repository. Initialize with: git init');
-        process.exit(1);
+        exitWithError('Not a git repository', {
+            exitCode: ExitCode.CONFIG_ERROR,
+            searchedIn: absolutePath,
+            suggestion: 'Initialize with: git init',
+        });
     }
     // Create .githooks directory
     const hooksDir = path.join(absolutePath, '.githooks');
@@ -315,59 +620,29 @@ function formatDefaultValue(value) {
  */
 function getConfigPath() {
     const platform = process.platform;
+    const home = os.homedir();
     if (platform === 'darwin') {
-        return path.join(os.homedir(), 'Library/Application Support/Claude/claude_desktop_config.json');
+        return path.join(home, 'Library/Application Support/Claude/claude_desktop_config.json');
     }
     else if (platform === 'win32') {
-        return path.join(process.env.APPDATA || '', 'Claude/claude_desktop_config.json');
+        // On Windows, use APPDATA if available, otherwise fall back to home/AppData/Roaming
+        const appData = process.env.APPDATA || path.join(home, 'AppData', 'Roaming');
+        return path.join(appData, 'Claude', 'claude_desktop_config.json');
     }
     else {
         // Linux/other
-        return path.join(os.homedir(), '.config/Claude/claude_desktop_config.json');
-    }
-}
-/**
- * Check if photon is installed globally
- * @returns "photon" if available globally (cross-platform), null otherwise
- */
-async function getGlobalPhotonPath() {
-    const { execFile } = await import('child_process');
-    const { promisify } = await import('util');
-    const execFileAsync = promisify(execFile);
-    try {
-        const command = process.platform === 'win32' ? 'where' : 'which';
-        const { stdout } = await execFileAsync(command, ['photon']);
-        const photonPath = stdout.trim().split('\n')[0]; // Take first match
-        if (photonPath) {
-            // Verify it's actually the @portel/photon package by checking version
-            try {
-                const { stdout: versionOutput } = await execFileAsync(photonPath, ['--version']);
-                // If it outputs a version, it's likely our photon
-                if (versionOutput.trim()) {
-                    // Return "photon" instead of full path for cross-platform compatibility
-                    // The shell will resolve it from PATH
-                    return 'photon';
-                }
-            }
-            catch {
-                // Version check failed, might not be our photon
-                return null;
-            }
-        }
+        return path.join(home, '.config/Claude/claude_desktop_config.json');
     }
-    catch {
-        // which/where command failed, photon not in PATH
-    }
-    return null;
 }
 /**
  * Validate configuration for an MCP
  */
 async function validateConfiguration(filePath, mcpName) {
-    console.log(`🔍 Validating configuration for: ${mcpName}\n`);
+    cliHeading(`🔍 Validating configuration for: ${mcpName}`);
+    cliSpacer();
     const params = await extractConstructorParams(filePath);
     if (params.length === 0) {
-        console.log('✅ No configuration required');
+        printSuccess('No configuration required for this MCP.');
         return;
     }
     let hasErrors = false;
@@ -381,15 +656,15 @@ async function validateConfiguration(filePath, mcpName) {
             results.push({
                 name: param.name,
                 envVar: envVarName,
-                status: '❌ MISSING (required)',
+                status: '❌ Missing (required)',
             });
         }
         else if (envValue) {
             results.push({
                 name: param.name,
                 envVar: envVarName,
-                status: '✅ SET',
-                value: envValue.length > 20 ? envValue.substring(0, 17) + '...' : envValue,
+                status: '✅ Set',
+                value: envValue.length > 20 ? `${envValue.substring(0, 17)}...` : envValue,
             });
         }
         else {
@@ -401,55 +676,51 @@ async function validateConfiguration(filePath, mcpName) {
             });
         }
     }
-    // Print results
-    console.log('Configuration Status:\n');
-    results.forEach(r => {
-        console.log(`  ${r.status} ${r.envVar}`);
+    printHeader('Configuration status');
+    results.forEach((r) => {
+        printInfo(`  ${r.status} ${r.envVar}`);
         if (r.value) {
-            console.log(`     Value: ${r.value}`);
+            printInfo(`     Value: ${r.value}`);
         }
-        console.log();
     });
+    cliSpacer();
     if (hasErrors) {
-        console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-        console.log('❌ Validation failed: Missing required environment variables');
-        console.log('\nRun: photon mcp ' + mcpName + ' --config');
-        console.log('     To see configuration template');
-        process.exit(1);
+        exitWithError('Validation failed: Missing required environment variables', {
+            exitCode: ExitCode.CONFIG_ERROR,
+            suggestion: `Run 'photon mcp ${mcpName} --config' to see the configuration template`,
+        });
     }
     else {
-        console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-        console.log('✅ Configuration valid!');
-        console.log('\nYou can now run: photon mcp ' + mcpName);
+        printSuccess('Configuration valid!');
+        cliHint(`Run: photon mcp ${mcpName}`);
     }
 }
 /**
  * Show configuration template for an MCP
  */
 async function showConfigTemplate(filePath, mcpName, workingDir = DEFAULT_WORKING_DIR) {
-    console.log(`📋 Configuration template for: ${mcpName}\n`);
+    cliHeading(`📋 Configuration template for: ${mcpName}`);
+    cliSpacer();
     const params = await extractConstructorParams(filePath);
     if (params.length === 0) {
-        console.log('✅ No configuration required for this MCP');
+        printSuccess('No configuration required for this MCP.');
         return;
     }
-    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-    console.log('Environment Variables:\n');
-    params.forEach(param => {
+    printHeader('Environment variables');
+    params.forEach((param) => {
         const envVarName = toEnvVarName(mcpName, param.name);
         const isRequired = !param.isOptional && !param.hasDefault;
         const status = isRequired ? '[REQUIRED]' : '[OPTIONAL]';
-        console.log(`  ${envVarName} ${status}`);
-        console.log(`    Type: ${param.type}`);
+        printInfo(`  ${envVarName} ${status}`);
+        printInfo(`    Type: ${param.type}`);
         if (param.hasDefault) {
-            console.log(`    Default: ${formatDefaultValue(param.defaultValue)}`);
+            printInfo(`    Default: ${formatDefaultValue(param.defaultValue)}`);
         }
-        console.log();
+        cliSpacer();
     });
-    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-    console.log('Claude Desktop Configuration:\n');
+    printHeader('Claude Desktop configuration');
     const envExample = {};
-    params.forEach(param => {
+    params.forEach((param) => {
         const envVarName = toEnvVarName(mcpName, param.name);
         if (!param.isOptional && !param.hasDefault) {
             envExample[envVarName] = `<your-${param.name}>`;
@@ -468,25 +739,19 @@ async function showConfigTemplate(filePath, mcpName, workingDir = DEFAULT_WORKIN
         },
     };
     console.log(JSON.stringify(config, null, 2));
-    console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-    console.log(`\nAdd this to: ${getConfigPath()}`);
-    console.log('\nValidate: photon mcp ' + mcpName + ' --validate');
-}
-// Get version from package.json
-let version = '1.0.0';
-try {
-    const packageJson = require('../package.json');
-    version = packageJson.version;
-}
-catch {
-    // Fallback version
+    cliSpacer();
+    cliHint(`Add this to: ${getConfigPath()}`);
+    cliHint(`Validate with: photon mcp ${mcpName} --validate`);
 }
+const version = PHOTON_VERSION;
 const program = new Command();
 program
     .name('photon')
     .description('Universal runtime for single-file TypeScript programs')
     .version(version)
     .option('--dir <path>', 'Photon directory (default: ~/.photon)', DEFAULT_WORKING_DIR)
+    .option('--log-level <level>', 'Set log verbosity (error|warn|info|debug)', 'info')
+    .option('--json-logs', 'Emit newline-delimited JSON logs for runtime output')
     .configureHelp({
     sortSubcommands: false,
     sortOptions: false,
@@ -495,6 +760,12 @@ program
 Runtime Commands:
   mcp <name>              Run a photon as MCP server (for AI assistants)
   cli <photon> [method]   Run photon methods from command line
+  sse <name>              Run Photon as HTTP server with SSE transport
+  beam                    Launch Photon Beam (interactive control panel)
+  serve                   Start local multi-tenant MCP hosting for development
+
+Hosting:
+  host <command>          Manage cloud hosting (preview, deploy)
 
 Package Management:
   add <name>              Install a photon from marketplace
@@ -525,49 +796,55 @@ program
     .description('Update marketplace indexes and check for CLI updates')
     .action(async () => {
     try {
-        const { printInfo, printSuccess, printWarning } = await import('./cli-formatter.js');
-        // Update all marketplace caches
-        printInfo('Refreshing marketplace indexes...\n');
+        const { printInfo, printSuccess, printWarning, printHeader } = await import('./cli-formatter.js');
         const { MarketplaceManager } = await import('./marketplace-manager.js');
         const manager = new MarketplaceManager();
         await manager.initialize();
-        const results = await manager.updateAllCaches();
-        for (const [marketplaceName, success] of results) {
+        const results = await runTask('Refreshing marketplace indexes', async () => {
+            return manager.updateAllCaches();
+        });
+        console.log('');
+        const entries = Array.from(results.entries());
+        let successCount = 0;
+        for (const [marketplaceName, success] of entries) {
             if (success) {
-                printSuccess(`${marketplaceName}`);
+                printSuccess(marketplaceName);
+                successCount++;
             }
             else {
                 printWarning(`${marketplaceName} (no manifest)`);
             }
         }
-        const successCount = Array.from(results.values()).filter(Boolean).length;
-        console.log('');
-        printInfo(`Updated ${successCount}/${results.size} marketplaces`);
-        // Check for CLI updates
-        console.log('');
-        printInfo('Checking for Photon CLI updates...');
+        printInfo(`\nUpdated ${successCount}/${entries.length} marketplaces`);
+        let latestVersion = null;
         try {
-            const { execSync } = await import('child_process');
-            const latestVersion = execSync('npm view @portel/photon version', {
-                encoding: 'utf-8',
-                timeout: 10000,
-            }).trim();
-            if (latestVersion && latestVersion !== version) {
-                console.log('');
-                printWarning(`New Photon version available: ${version} → ${latestVersion}`);
+            latestVersion = await runTask('Checking for Photon CLI updates', async () => {
+                const { execSync } = await import('child_process');
+                return execSync('npm view @portel/photon version', {
+                    encoding: 'utf-8',
+                    timeout: 10000,
+                }).trim();
+            });
+        }
+        catch {
+            printWarning('\nCould not check for CLI updates');
+        }
+        if (latestVersion) {
+            console.log('');
+            if (latestVersion !== version) {
+                printHeader('Update available');
+                printWarning(`Current: ${version}`);
+                printInfo(`Latest:  ${latestVersion}`);
                 printInfo(`Update with: npm install -g @portel/photon`);
             }
             else {
                 printSuccess(`Photon CLI is up to date (${version})`);
             }
         }
-        catch {
-            printWarning('Could not check for CLI updates');
-        }
     }
     catch (error) {
         const { printError } = await import('./cli-formatter.js');
-        printError(error.message);
+        printError(getErrorMessage(error));
         process.exit(1);
     }
 });
@@ -579,32 +856,127 @@ program
     .option('--dev', 'Enable development mode with hot reload')
     .option('--validate', 'Validate configuration without running server')
     .option('--config', 'Show configuration template and exit')
-    .action(async (name, options, command) => {
+    .option('--transport <type>', 'Transport type: stdio (default) or sse', 'stdio')
+    .option('--port <number>', 'Port for SSE transport (default: 3000)', '3000')
+    .action(async (rawName, options, command) => {
     try {
+        // Parse extended name format (e.g., "alice/repo:rss-feed")
+        const { name, marketplaceSource } = parsePhotonSpec(rawName);
         // Get working directory from global options
         const workingDir = program.opts().dir || DEFAULT_WORKING_DIR;
-        // Resolve file path from name in working directory
-        const filePath = await resolvePhotonPath(name, workingDir);
+        const logOptions = getLogOptionsFromCommand(command);
+        // Resolve file path - check bundled photons first, then user directory
+        let filePath = await resolvePhotonPathWithBundled(name, workingDir);
+        // Auto-install from marketplace if not found locally
+        let unresolvedPhoton;
         if (!filePath) {
-            console.error(`❌ MCP not found: ${name}`);
-            console.error(`Searched in: ${workingDir}`);
-            console.error(`Tip: Use 'photon info' to see available MCPs`);
-            process.exit(1);
+            const { MarketplaceManager, calculateHash } = await import('./marketplace-manager.js');
+            const manager = new MarketplaceManager();
+            await manager.initialize();
+            // If marketplace source given, add it (persistent, idempotent)
+            if (marketplaceSource) {
+                const { marketplace: addedMp, added } = await manager.add(marketplaceSource);
+                if (added) {
+                    console.error(`Added marketplace: ${addedMp.name}`);
+                    await manager.updateMarketplaceCache(addedMp.name);
+                }
+            }
+            // Check for conflicts (multiple sources)
+            const conflict = await manager.checkConflict(name);
+            if (conflict.sources.length === 0) {
+                // Not found anywhere
+                exitWithError(`MCP not found: ${name}`, {
+                    exitCode: ExitCode.NOT_FOUND,
+                    searchedIn: workingDir,
+                    suggestion: DEFAULT_BUNDLED_PHOTONS.includes(name)
+                        ? `'${name}' is a bundled photon but could not be found`
+                        : marketplaceSource
+                            ? `Photon '${name}' not found in ${marketplaceSource}`
+                            : "Use 'photon search <name>' to find it or 'photon marketplace add <source>' to add a marketplace",
+                });
+            }
+            else if (conflict.sources.length === 1 || !conflict.hasConflict) {
+                // Single source — auto-download
+                const source = conflict.sources[0];
+                console.error(`Installing ${name} from ${source.marketplace.name}...`);
+                const result = await manager.fetchMCP(name);
+                if (!result) {
+                    exitWithError(`Failed to download: ${name}`, {
+                        exitCode: ExitCode.ERROR,
+                        suggestion: 'Check your internet connection and marketplace configuration',
+                    });
+                }
+                // Ensure working directory exists and save
+                await ensureWorkingDir(workingDir);
+                const targetPath = path.join(workingDir, `${name}.photon.ts`);
+                await fs.writeFile(targetPath, result.content, 'utf-8');
+                // Save metadata
+                if (source.metadata) {
+                    const contentHash = calculateHash(result.content);
+                    await manager.savePhotonMetadata(`${name}.photon.ts`, source.marketplace, source.metadata, contentHash);
+                    // Download assets
+                    if (source.metadata.assets && source.metadata.assets.length > 0) {
+                        const assets = await manager.fetchAssets(source.marketplace, source.metadata.assets);
+                        for (const [assetPath, content] of assets) {
+                            const assetTarget = path.join(workingDir, assetPath);
+                            const assetDir = path.dirname(assetTarget);
+                            await fs.mkdir(assetDir, { recursive: true });
+                            await fs.writeFile(assetTarget, content, 'utf-8');
+                        }
+                    }
+                }
+                console.error(`Installed ${name}`);
+                filePath = targetPath;
+            }
+            else {
+                // Multiple sources — defer to server for elicitation
+                unresolvedPhoton = {
+                    name,
+                    workingDir,
+                    sources: conflict.sources,
+                    recommendation: conflict.recommendation,
+                };
+            }
         }
-        // Handle --validate flag
+        // Handle --validate flag (requires resolved filePath)
         if (options.validate) {
+            if (!filePath) {
+                exitWithError(`Cannot validate: ${name} has multiple sources. Install it first with 'photon add ${name}'.`, {
+                    exitCode: ExitCode.CONFIG_ERROR,
+                });
+            }
             await validateConfiguration(filePath, name);
             return;
         }
         // Handle --config flag
         if (options.config) {
+            if (!filePath) {
+                exitWithError(`Cannot show config: ${name} has multiple sources. Install it first with 'photon add ${name}'.`, {
+                    exitCode: ExitCode.CONFIG_ERROR,
+                });
+            }
             await showConfigTemplate(filePath, name, workingDir);
             return;
         }
+        // Validate transport option
+        const transport = options.transport;
+        if (transport !== 'stdio' && transport !== 'sse') {
+            exitWithError(`Invalid transport: ${options.transport}`, {
+                exitCode: ExitCode.INVALID_ARGUMENT,
+                suggestion: 'Valid options: stdio, sse',
+            });
+        }
+        // Set PHOTON_NAME for daemon broker pub/sub to work
+        // This ensures channel messages go to the correct daemon socket
+        process.env.PHOTON_NAME = name;
         // Start MCP server
         const server = new PhotonServer({
-            filePath,
+            filePath: filePath || '', // empty when unresolved — server handles it
             devMode: options.dev,
+            transport,
+            port: parseInt(options.port, 10),
+            logOptions: { ...logOptions, scope: transport },
+            unresolvedPhoton,
         });
         // Handle shutdown signals
         const shutdown = async () => {
@@ -616,9 +988,9 @@ program
         process.on('SIGTERM', shutdown);
         // Start the server
         await server.start();
-        // Start file watcher in dev mode
-        if (options.dev) {
-            const watcher = new FileWatcher(server, filePath);
+        // Start file watcher in dev mode (only if resolved)
+        if (options.dev && filePath) {
+            const watcher = new FileWatcher(server, filePath, server.createScopedLogger('watcher'));
             watcher.start();
             // Clean up watcher on shutdown
             process.on('SIGINT', async () => {
@@ -630,288 +1002,305 @@ program
         }
     }
     catch (error) {
-        console.error(`❌ Error: ${error.message}`);
+        logger.error(`Error: ${getErrorMessage(error)}`);
         process.exit(1);
     }
 });
-// Info command: show installed and available Photons
+// SSE command: quick SSE server with auto port detection (formerly serve)
 program
-    .command('info', { hidden: true })
-    .argument('[name]', 'Photon name to show details for (shows all if omitted)')
-    .option('--mcp', 'Output as MCP server configuration')
-    .alias('list')
-    .alias('ls')
-    .description('Show installed and available Photons')
+    .command('sse', { hidden: true })
+    .argument('<name>', 'Photon name (without .photon.ts extension)')
+    .option('-p, --port <number>', 'Port to start from (auto-finds available)', '3000')
+    .option('--dev', 'Enable development mode with hot reload')
+    .description('Run Photon as HTTP server with SSE transport (auto port detection)')
     .action(async (name, options, command) => {
     try {
-        const { formatOutput, printInfo, printError, STATUS } = await import('./cli-formatter.js');
-        // Get working directory from global/parent options
-        const parentOpts = command.parent?.opts() || {};
-        const workingDir = parentOpts.dir || DEFAULT_WORKING_DIR;
-        const asMcp = options.mcp || false;
-        const mcps = await listPhotonMCPs(workingDir);
-        // Initialize marketplace manager for all operations
-        const { MarketplaceManager } = await import('./marketplace-manager.js');
-        const manager = new MarketplaceManager();
-        await manager.initialize();
-        // Show single Photon details
-        if (name) {
-            const filePath = await resolvePhotonPath(name, workingDir);
-            const isInstalled = !!filePath;
-            if (asMcp) {
-                // MCP config only works for installed photons
-                if (!isInstalled) {
-                    printError(`'${name}' is not installed`);
-                    printInfo(`Install with: photon add ${name}`);
-                    process.exit(1);
-                }
-                // Show as MCP config for single Photon
-                const constructorParams = await extractConstructorParams(filePath);
-                const env = {};
-                for (const param of constructorParams) {
-                    const envVarName = toEnvVarName(name, param.name);
-                    const defaultDisplay = param.defaultValue !== undefined
-                        ? formatDefaultValue(param.defaultValue)
-                        : `<your-${param.name}>`;
-                    env[envVarName] = defaultDisplay;
-                }
-                // Check for global photon installation
-                const globalPhotonPath = await getGlobalPhotonPath();
-                const needsWorkingDir = workingDir !== DEFAULT_WORKING_DIR;
-                const config = globalPhotonPath
-                    ? {
-                        command: globalPhotonPath,
-                        args: needsWorkingDir
-                            ? ['mcp', name, '--dir', workingDir]
-                            : ['mcp', name],
-                        ...(Object.keys(env).length > 0 && { env }),
-                    }
-                    : {
-                        command: 'npx',
-                        args: needsWorkingDir
-                            ? ['@portel/photon', 'mcp', name, '--dir', workingDir]
-                            : ['@portel/photon', 'mcp', name],
-                        ...(Object.keys(env).length > 0 && { env }),
-                    };
-                // Get OS-specific config path
-                const configPath = getConfigPath();
-                console.log(`# Photon MCP Server Configuration: ${name}`);
-                console.log(`# Add to mcpServers in: ${configPath}\n`);
-                console.log(JSON.stringify({ [name]: config }, null, 2));
-            }
-            else {
-                // Show info for specific photon - both local and marketplace
-                // Show local installation if present
-                if (isInstalled) {
-                    const { PhotonDocExtractor } = await import('./photon-doc-extractor.js');
-                    const extractor = new PhotonDocExtractor(filePath);
-                    const photonMetadata = await extractor.extractFullMetadata();
-                    const fileName = `${name}.photon.ts`;
-                    const metadata = await manager.getPhotonInstallMetadata(fileName);
-                    const isModified = metadata ? await manager.isPhotonModified(filePath, fileName) : false;
-                    printInfo(`Installed in ${workingDir}:\n`);
-                    // Build info as tree structure
-                    const infoData = {
-                        name: name,
-                        version: photonMetadata.version || '-',
-                        location: filePath,
-                    };
-                    if (photonMetadata.description) {
-                        infoData.description = photonMetadata.description;
-                    }
-                    if (metadata) {
-                        infoData.installed = new Date(metadata.installedAt).toLocaleDateString();
-                        infoData.source = metadata.marketplace;
-                        if (isModified) {
-                            infoData.status = 'modified locally';
-                        }
-                    }
-                    const toolCount = photonMetadata.tools?.length || 0;
-                    if (toolCount > 0) {
-                        infoData.tools = toolCount;
-                    }
-                    formatOutput(infoData, 'tree');
-                    console.log('');
-                    // Show appropriate run command
-                    if (metadata && !isModified) {
-                        printInfo(`Run with: photon mcp ${name}`);
-                        printInfo(`To customize: Copy to a new name and run with --dev for hot reload`);
-                    }
-                    else if (metadata && isModified) {
-                        printInfo(`Run with: photon mcp ${name} --dev`);
-                        printInfo(`Note: Modified from marketplace - consider renaming to avoid upgrade conflicts`);
-                    }
-                    else {
-                        printInfo(`Run with: photon mcp ${name} --dev`);
-                    }
-                    console.log('');
-                }
-                // Show marketplace availability in tree format
-                const searchResults = await manager.search(name);
-                if (searchResults.size > 0) {
-                    printInfo('Available in marketplaces:\n');
-                    // Get all sources for this specific photon
-                    const sources = searchResults.get(name);
-                    if (sources && sources.length > 0) {
-                        // Get local installation info to mark which one is installed
-                        const fileName = `${name}.photon.ts`;
-                        const installMetadata = await manager.getPhotonInstallMetadata(fileName);
-                        // Build marketplace data as tree
-                        const marketplaceData = {};
-                        for (const source of sources) {
-                            const isCurrentlyInstalled = installMetadata?.marketplace === source.marketplace.name;
-                            const version = source.metadata?.version || 'unknown';
-                            marketplaceData[source.marketplace.name] = {
-                                version,
-                                source: source.marketplace.repo,
-                                status: isCurrentlyInstalled ? 'installed' : '-',
-                            };
-                        }
-                        formatOutput(marketplaceData, 'tree');
-                    }
-                }
-                else if (!isInstalled) {
-                    printError(`'${name}' not found locally or in any marketplace`);
-                    printInfo(`Tip: Use 'photon search <query>' to find similar MCPs`);
-                    process.exit(1);
-                }
-            }
-            return;
-        }
-        // Show all Photons
-        if (asMcp) {
-            // MCP config mode for all Photons
-            const allConfigs = {};
-            // Check for global photon installation once
-            const globalPhotonPath = await getGlobalPhotonPath();
-            const needsWorkingDir = workingDir !== DEFAULT_WORKING_DIR;
-            for (const mcpName of mcps) {
-                const filePath = await resolvePhotonPath(mcpName, workingDir);
-                if (!filePath)
-                    continue;
-                const constructorParams = await extractConstructorParams(filePath);
-                const env = {};
-                for (const param of constructorParams) {
-                    const envVarName = toEnvVarName(mcpName, param.name);
-                    const defaultDisplay = param.defaultValue !== undefined
-                        ? formatDefaultValue(param.defaultValue)
-                        : `<your-${param.name}>`;
-                    env[envVarName] = defaultDisplay;
-                }
-                allConfigs[mcpName] = globalPhotonPath
-                    ? {
-                        command: globalPhotonPath,
-                        args: needsWorkingDir
-                            ? ['mcp', mcpName, '--dir', workingDir]
-                            : ['mcp', mcpName],
-                        ...(Object.keys(env).length > 0 && { env }),
-                    }
-                    : {
-                        command: 'npx',
-                        args: needsWorkingDir
-                            ? ['@portel/photon', 'mcp', mcpName, '--dir', workingDir]
-                            : ['@portel/photon', 'mcp', mcpName],
-                        ...(Object.keys(env).length > 0 && { env }),
-                    };
-            }
-            // Get OS-specific config path
-            const configPath = getConfigPath();
-            console.log(`# Photon MCP Server Configuration (${mcps.length} servers)`);
-            console.log(`# Add to mcpServers in: ${configPath}\n`);
-            console.log(JSON.stringify({ mcpServers: allConfigs }, null, 2));
-            return;
+        // Get working directory from global options
+        const workingDir = program.opts().dir || DEFAULT_WORKING_DIR;
+        const logOptions = getLogOptionsFromCommand(command);
+        // Resolve file path from name
+        const filePath = await resolvePhotonPath(name, workingDir);
+        if (!filePath) {
+            exitWithError(`Photon not found: ${name}`, {
+                exitCode: ExitCode.NOT_FOUND,
+                searchedIn: workingDir,
+                suggestion: "Use 'photon info' to see available photons",
+            });
         }
-        // Normal list mode - show both installed and available
-        // Show installed photons as table
-        if (mcps.length > 0) {
-            printInfo(`Installed in ${workingDir} (${mcps.length}):\n`);
-            const tableData = [];
-            for (const mcpName of mcps) {
-                const fileName = `${mcpName}.photon.ts`;
-                const filePath = path.join(workingDir, fileName);
-                // Get installation metadata
-                const metadata = await manager.getPhotonInstallMetadata(fileName);
-                if (metadata) {
-                    // Has metadata - show version and status
-                    const isModified = await manager.isPhotonModified(filePath, fileName);
-                    tableData.push({
-                        name: mcpName,
-                        version: metadata.version,
-                        source: metadata.marketplace,
-                        status: isModified ? 'modified' : STATUS.OK,
-                    });
-                }
-                else {
-                    // No metadata - local or pre-metadata Photon
-                    tableData.push({
-                        name: mcpName,
-                        version: '-',
-                        source: 'local',
-                        status: STATUS.OK,
-                    });
-                }
-            }
-            formatOutput(tableData, 'table');
-            console.log('');
+        // Find available port
+        const startPort = parseInt(options.port, 10);
+        const port = await findAvailablePort(startPort);
+        if (port !== startPort) {
+            console.error(`⚠️  Port ${startPort} is in use, using ${port} instead\n`);
         }
-        else {
-            printInfo(`No photons installed in ${workingDir}`);
-            printInfo(`Install with: photon add <name>\n`);
-        }
-        // Show marketplace availability in tree format
-        printInfo('Available in marketplaces:\n');
-        const marketplaces = manager.getAll().filter(m => m.enabled);
-        const counts = await manager.getMarketplaceCounts();
-        // Build marketplace tree
-        const marketplaceTree = {};
-        for (const marketplace of marketplaces) {
-            const count = counts.get(marketplace.name) || 0;
-            if (count > 0) {
-                // Get a few sample photons from this marketplace
-                const manifest = await manager['getCachedManifest'](marketplace.name);
-                if (manifest && manifest.photons) {
-                    const samples = manifest.photons.slice(0, 3);
-                    const photonList = {};
-                    samples.forEach((photon) => {
-                        const installedMark = mcps.includes(photon.name) ? ' (installed)' : '';
-                        photonList[photon.name] = `v${photon.version}${installedMark}`;
-                    });
-                    if (count > 3) {
-                        photonList['...'] = `${count - 3} more`;
-                    }
-                    marketplaceTree[`${marketplace.name} (${marketplace.repo})`] = photonList;
-                }
-            }
-            else {
-                marketplaceTree[marketplace.name] = 'no manifest';
-            }
+        // Start SSE server
+        const server = new PhotonServer({
+            filePath,
+            devMode: options.dev,
+            transport: 'sse',
+            port,
+            logOptions: { ...logOptions, scope: 'sse' },
+        });
+        // Handle shutdown signals
+        const shutdown = async () => {
+            console.error('\nShutting down...');
+            await server.stop();
+            process.exit(0);
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+        // Start the server
+        await server.start();
+        // Start file watcher in dev mode
+        if (options.dev) {
+            const watcher = new FileWatcher(server, filePath, server.createScopedLogger('watcher'));
+            watcher.start();
+            process.on('SIGINT', async () => {
+                await watcher.stop();
+            });
+            process.on('SIGTERM', async () => {
+                await watcher.stop();
+            });
         }
-        formatOutput(marketplaceTree, 'tree');
-        console.log('');
-        printInfo(`Details: photon info <name>`);
-        printInfo(`MCP config: photon info <name> --mcp`);
     }
     catch (error) {
-        const { printError } = await import('./cli-formatter.js');
-        printError(error.message);
+        logger.error(`Error: ${getErrorMessage(error)}`);
         process.exit(1);
     }
 });
-// Search command: search for MCPs across marketplaces
+// Beam command: interactive UI for all photons
 program
-    .command('search', { hidden: true })
-    .argument('<query>', 'MCP name or keyword to search for')
-    .description('Search for MCP in all enabled marketplaces')
-    .action(async (query) => {
+    .command('beam', { hidden: true })
+    .option('-p, --port <number>', 'Port to start from (auto-finds available)', '3000')
+    .option('-o, --open', 'Auto-open browser after starting')
+    .option('--no-open', 'Do not auto-open browser')
+    .description('Launch Photon Beam - interactive control panel for all your photons')
+    .action(async (options, command) => {
     try {
-        const { MarketplaceManager } = await import('./marketplace-manager.js');
-        const { formatOutput, printInfo, printError } = await import('./cli-formatter.js');
-        const manager = new MarketplaceManager();
-        await manager.initialize();
-        // Auto-update stale caches
-        const updated = await manager.autoUpdateStaleCaches();
-        if (updated) {
-            printInfo('Refreshed marketplace data...\n');
+        // Get working directory from global options
+        const workingDir = program.opts().dir || DEFAULT_WORKING_DIR;
+        // Find available port
+        const startPort = parseInt(options.port, 10);
+        const port = await findAvailablePort(startPort);
+        if (port !== startPort) {
+            console.error(`⚠️  Port ${startPort} is in use, using ${port} instead\n`);
+        }
+        // Import and start Beam server
+        const { startBeam } = await import('./auto-ui/beam.js');
+        await startBeam(workingDir, port);
+        // Auto-open browser if requested
+        // Use actual bound port from BEAM_PORT env var (set by startBeam after binding)
+        if (options.open) {
+            const actualPort = process.env.BEAM_PORT || port;
+            const url = `http://localhost:${actualPort}`;
+            const { exec } = await import('child_process');
+            const openCmd = process.platform === 'darwin'
+                ? 'open'
+                : process.platform === 'win32'
+                    ? 'start'
+                    : 'xdg-open';
+            exec(`${openCmd} ${url}`, (err) => {
+                if (err)
+                    logger.debug(`Could not auto-open browser: ${err.message}`);
+            });
+        }
+        // Handle shutdown signals
+        const shutdown = async () => {
+            console.error('\nShutting down Photon Beam...');
+            // Gracefully close external MCP clients to prevent ugly tracebacks
+            try {
+                const { stopBeam } = await import('./auto-ui/beam.js');
+                await stopBeam();
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            process.exit(0);
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+    }
+    catch (error) {
+        logger.error(`Error: ${getErrorMessage(error)}`);
+        process.exit(1);
+    }
+});
+// Serve command: multi-tenant MCP hosting (formerly serv)
+program
+    .command('serve', { hidden: true })
+    .option('-p, --port <number>', 'Port to run on', '4000')
+    .option('-d, --debug', 'Enable debug logging')
+    .description('Start local multi-tenant MCP hosting for development')
+    .action(async (options) => {
+    try {
+        const port = parseInt(options.port, 10);
+        const availablePort = await findAvailablePort(port);
+        if (availablePort !== port) {
+            console.error(`⚠️  Port ${port} is in use, using ${availablePort} instead\n`);
+        }
+        // Import and start LocalServ
+        const { createLocalServ, getTestToken } = await import('./serv/local.js');
+        const { serv, tenant, user } = createLocalServ({
+            port: availablePort,
+            baseUrl: `http://localhost:${availablePort}`,
+            debug: options.debug,
+        });
+        // Get a test token
+        const token = await getTestToken(serv, tenant, user);
+        console.error(`
+⚡ Photon Serve (Multi-tenant Development)
+
+   URL:     http://localhost:${availablePort}
+   Tenant:  ${tenant.slug} (${tenant.name})
+   User:    ${user.email}
+
+   Test Token:
+   ${token}
+
+   MCP Endpoint:
+   http://localhost:${availablePort}/tenant/${tenant.slug}/mcp
+
+   Well-Known:
+   http://localhost:${availablePort}/.well-known/oauth-protected-resource
+
+Press Ctrl+C to stop
+`);
+        // Simple HTTP server
+        const http = await import('http');
+        const server = http.createServer(async (req, res) => {
+            const url = req.url || '/';
+            const method = req.method || 'GET';
+            const headers = {};
+            for (const [key, value] of Object.entries(req.headers)) {
+                if (typeof value === 'string')
+                    headers[key] = value;
+            }
+            // Read body if present
+            let body = '';
+            if (method === 'POST') {
+                body = await new Promise((resolve) => {
+                    let data = '';
+                    req.on('data', (chunk) => (data += chunk));
+                    req.on('end', () => resolve(data));
+                });
+            }
+            const result = await serv.handleRequest(method, url, headers, body);
+            res.writeHead(result.status, result.headers);
+            res.end(result.body);
+        });
+        server.listen(availablePort);
+        // Handle shutdown
+        const shutdown = async () => {
+            console.error('\nShutting down Photon Serve...');
+            await serv.shutdown();
+            server.close();
+            process.exit(0);
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+    }
+    catch (error) {
+        logger.error(`Error: ${getErrorMessage(error)}`);
+        process.exit(1);
+    }
+});
+// Host command: manage hosting and deployment (preview, deploy)
+const host = program
+    .command('host', { hidden: true })
+    .description('Manage cloud hosting and deployment');
+host
+    .command('preview')
+    .argument('<target>', 'Deployment target: cloudflare (or cf)')
+    .argument('<name>', 'Photon name (without .photon.ts extension)')
+    .option('--output <dir>', 'Output directory for generated project')
+    .description('Run Photon locally in a simulated deployment environment')
+    .action(async (target, name, options) => {
+    try {
+        // Get working directory from global options
+        const workingDir = program.opts().dir || DEFAULT_WORKING_DIR;
+        // Resolve file path from name
+        const photonPath = await resolvePhotonPath(name, workingDir);
+        if (!photonPath) {
+            logger.error(`Photon not found: ${name}`);
+            console.error(`Searched in: ${workingDir}`);
+            console.error(`Tip: Use 'photon info' to see available photons`);
+            process.exit(1);
+        }
+        const normalizedTarget = target.toLowerCase();
+        if (normalizedTarget === 'cloudflare' || normalizedTarget === 'cf') {
+            const { devCloudflare } = await import('./deploy/cloudflare.js');
+            await devCloudflare({
+                photonPath,
+                outputDir: options.output,
+            });
+        }
+        else {
+            logger.error(`Unknown target: ${target}`);
+            console.error('Supported targets: cloudflare (cf)');
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        logger.error(`Error: ${getErrorMessage(error)}`);
+        process.exit(1);
+    }
+});
+host
+    .command('deploy')
+    .argument('<target>', 'Deployment target: cloudflare (or cf)')
+    .argument('<name>', 'Photon name (without .photon.ts extension)')
+    .option('--dev', 'Enable Beam UI in deployment')
+    .option('--dry-run', 'Generate project without deploying')
+    .option('--output <dir>', 'Output directory for generated project')
+    .description('Deploy a Photon to cloud platforms')
+    .action(async (target, name, options) => {
+    try {
+        // Get working directory from global options
+        const workingDir = program.opts().dir || DEFAULT_WORKING_DIR;
+        // Resolve file path from name
+        const photonPath = await resolvePhotonPath(name, workingDir);
+        if (!photonPath) {
+            logger.error(`Photon not found: ${name}`);
+            console.error(`Searched in: ${workingDir}`);
+            console.error(`Tip: Use 'photon info' to see available photons`);
+            process.exit(1);
+        }
+        const normalizedTarget = target.toLowerCase();
+        if (normalizedTarget === 'cloudflare' || normalizedTarget === 'cf') {
+            const { deployToCloudflare } = await import('./deploy/cloudflare.js');
+            await deployToCloudflare({
+                photonPath,
+                devMode: options.dev,
+                dryRun: options.dryRun,
+                outputDir: options.output,
+            });
+        }
+        else {
+            logger.error(`Unknown deployment target: ${target}`);
+            console.error('Supported targets: cloudflare (cf)');
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        logger.error(`Deployment failed: ${getErrorMessage(error)}`);
+        process.exit(1);
+    }
+});
+// Search command: search for MCPs across marketplaces
+program
+    .command('search', { hidden: true })
+    .argument('<query>', 'MCP name or keyword to search for')
+    .description('Search for MCP in all enabled marketplaces')
+    .action(async (query) => {
+    try {
+        const { MarketplaceManager } = await import('./marketplace-manager.js');
+        const { formatOutput, printInfo, printError } = await import('./cli-formatter.js');
+        const manager = new MarketplaceManager();
+        await manager.initialize();
+        // Auto-update stale caches
+        const updated = await manager.autoUpdateStaleCaches();
+        if (updated) {
+            printInfo('Refreshed marketplace data...\n');
         }
         printInfo(`Searching for '${query}' in marketplaces...`);
         const results = await manager.search(query);
@@ -926,9 +1315,10 @@ program
             for (const entry of entries) {
                 tableData.push({
                     name: mcpName,
-                    version: entry.metadata?.version || '-',
+                    version: entry.metadata?.version || PHOTON_VERSION,
                     description: entry.metadata?.description
-                        ? entry.metadata.description.substring(0, 50) + (entry.metadata.description.length > 50 ? '...' : '')
+                        ? entry.metadata.description.substring(0, 50) +
+                            (entry.metadata.description.length > 50 ? '...' : '')
                         : '-',
                     marketplace: entry.marketplace.name,
                 });
@@ -940,7 +1330,7 @@ program
     }
     catch (error) {
         const { printError } = await import('./cli-formatter.js');
-        printError(error.message);
+        printError(getErrorMessage(error));
         process.exit(1);
     }
 });
@@ -964,7 +1354,7 @@ maker
         // Check if file already exists
         try {
             await fs.access(filePath);
-            console.error(`❌ File already exists: ${filePath}`);
+            logger.error(`File already exists: ${filePath}`);
             process.exit(1);
         }
         catch {
@@ -984,18 +1374,16 @@ maker
         // Convert kebab-case to PascalCase for class name
         const className = name
             .split(/[-_]/)
-            .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+            .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
             .join('');
-        const content = template
-            .replace(/TemplateName/g, className)
-            .replace(/template-name/g, name);
+        const content = template.replace(/TemplateName/g, className).replace(/template-name/g, name);
         // Write file
         await fs.writeFile(filePath, content, 'utf-8');
         console.error(`✅ Created ${fileName} in ${workingDir}`);
         console.error(`Run with: photon mcp ${name} --dev`);
     }
     catch (error) {
-        console.error(`❌ Error: ${error.message}`);
+        logger.error(`Error: ${getErrorMessage(error)}`);
         process.exit(1);
     }
 });
@@ -1011,10 +1399,11 @@ maker
         // Resolve file path from name in working directory
         const filePath = await resolvePhotonPath(name, workingDir);
         if (!filePath) {
-            console.error(`❌ Photon not found: ${name}`);
-            console.error(`Searched in: ${workingDir}`);
-            console.error(`Tip: Use 'photon info' to see available photons`);
-            process.exit(1);
+            exitWithError(`Photon not found: ${name}`, {
+                exitCode: ExitCode.NOT_FOUND,
+                searchedIn: workingDir,
+                suggestion: "Use 'photon info' to see available photons",
+            });
         }
         console.error(`Validating ${path.basename(filePath)}...\n`);
         // Import loader and try to load
@@ -1030,7 +1419,7 @@ maker
         process.exit(0);
     }
     catch (error) {
-        console.error(`❌ Validation failed: ${error.message}`);
+        logger.error(`Validation failed: ${getErrorMessage(error)}`);
         process.exit(1);
     }
 });
@@ -1057,8 +1446,8 @@ maker
         }
     }
     catch (error) {
-        console.error(`❌ Error: ${error.message}`);
-        if (process.env.DEBUG) {
+        logger.error(`Error: ${getErrorMessage(error)}`);
+        if (process.env.DEBUG && error instanceof Error) {
             console.error(error.stack);
         }
         process.exit(1);
@@ -1077,848 +1466,342 @@ maker
         await performMarketplaceInit(dirPath, options);
     }
     catch (error) {
-        console.error(`❌ Error: ${error.message}`);
-        if (process.env.DEBUG) {
+        logger.error(`Error: ${getErrorMessage(error)}`);
+        if (process.env.DEBUG && error instanceof Error) {
             console.error(error.stack);
         }
         process.exit(1);
     }
 });
-// Marketplace command: manage MCP marketplaces
-const marketplace = program
-    .command('marketplace', { hidden: true })
-    .description('Manage MCP marketplaces');
-marketplace
-    .command('list')
-    .description('List all configured marketplaces')
-    .action(async () => {
-    try {
-        const { MarketplaceManager } = await import('./marketplace-manager.js');
-        const { formatOutput, printInfo, STATUS } = await import('./cli-formatter.js');
-        const manager = new MarketplaceManager();
-        await manager.initialize();
-        const marketplaces = manager.getAll();
-        if (marketplaces.length === 0) {
-            printInfo('No marketplaces configured');
-            printInfo('Add one with: photon marketplace add portel-dev/photons');
-            return;
-        }
-        // Get MCP counts
-        const counts = await manager.getMarketplaceCounts();
-        // Build table data
-        const tableData = marketplaces.map(m => ({
-            name: m.name,
-            source: m.source || m.repo || '-',
-            photons: counts.get(m.name) || 0,
-            status: m.enabled ? STATUS.OK : STATUS.OFF,
-        }));
-        printInfo(`Configured marketplaces (${marketplaces.length}):\n`);
-        formatOutput(tableData, 'table');
-    }
-    catch (error) {
-        const { printError } = await import('./cli-formatter.js');
-        printError(error.message);
-        process.exit(1);
-    }
-});
-marketplace
-    .command('add')
-    .argument('<repo>', 'GitHub repository (username/repo or github.com URL)')
-    .description('Add a new MCP marketplace from GitHub')
-    .action(async (repo) => {
+// maker diagram: generate Mermaid diagram for a Photon
+maker
+    .command('diagram <photon>')
+    .option('--dir <path>', 'Directory containing photon (defaults to current directory)')
+    .description('Generate Mermaid diagram for a Photon')
+    .action(async (photonName, options) => {
     try {
-        const { MarketplaceManager } = await import('./marketplace-manager.js');
-        const manager = new MarketplaceManager();
-        await manager.initialize();
-        const { marketplace: result, added } = await manager.add(repo);
-        if (added) {
-            console.error(`✅ Added marketplace: ${result.name}`);
-            console.error(`Source: ${repo}`);
-            console.error(`URL: ${result.url}`);
-            // Auto-fetch marketplace.json
-            console.error(`Fetching marketplace metadata...`);
-            const success = await manager.updateMarketplaceCache(result.name);
-            if (success) {
-                console.error(`✅ Marketplace ready to use`);
+        const { PhotonDocExtractor } = await import('./photon-doc-extractor.js');
+        // Resolve photon path
+        const dirPath = options.dir || '.';
+        let photonPath = photonName;
+        // If not a path, look in the directory
+        if (!photonName.includes('/') && !photonName.includes('\\')) {
+            if (!photonName.endsWith('.photon.ts')) {
+                photonName = `${photonName}.photon.ts`;
             }
+            photonPath = path.resolve(dirPath, photonName);
         }
         else {
-            console.error(`ℹ️  Marketplace already exists: ${result.name}`);
-            console.error(`Source: ${result.source}`);
-            console.error(`Skipping duplicate addition`);
-        }
-    }
-    catch (error) {
-        console.error(`❌ Error: ${error.message}`);
-        process.exit(1);
-    }
-});
-marketplace
-    .command('remove')
-    .argument('<name>', 'Marketplace name')
-    .description('Remove a marketplace')
-    .action(async (name) => {
-    try {
-        const { MarketplaceManager } = await import('./marketplace-manager.js');
-        const manager = new MarketplaceManager();
-        await manager.initialize();
-        const removed = await manager.remove(name);
-        if (removed) {
-            console.error(`✅ Removed marketplace: ${name}`);
-        }
-        else {
-            console.error(`❌ Marketplace '${name}' not found`);
-            process.exit(1);
-        }
-    }
-    catch (error) {
-        console.error(`❌ Error: ${error.message}`);
-        process.exit(1);
-    }
-});
-marketplace
-    .command('enable')
-    .argument('<name>', 'Marketplace name')
-    .description('Enable a marketplace')
-    .action(async (name) => {
-    try {
-        const { MarketplaceManager } = await import('./marketplace-manager.js');
-        const manager = new MarketplaceManager();
-        await manager.initialize();
-        const success = await manager.setEnabled(name, true);
-        if (success) {
-            console.error(`✅ Enabled marketplace: ${name}`);
-        }
-        else {
-            console.error(`❌ Marketplace '${name}' not found`);
-            process.exit(1);
-        }
-    }
-    catch (error) {
-        console.error(`❌ Error: ${error.message}`);
-        process.exit(1);
-    }
-});
-marketplace
-    .command('disable')
-    .argument('<name>', 'Marketplace name')
-    .description('Disable a marketplace')
-    .action(async (name) => {
-    try {
-        const { MarketplaceManager } = await import('./marketplace-manager.js');
-        const manager = new MarketplaceManager();
-        await manager.initialize();
-        const success = await manager.setEnabled(name, false);
-        if (success) {
-            console.error(`✅ Disabled marketplace: ${name}`);
+            photonPath = path.resolve(photonName);
         }
-        else {
-            console.error(`❌ Marketplace '${name}' not found`);
+        if (!existsSync(photonPath)) {
+            logger.error(`Photon not found: ${photonPath}`);
             process.exit(1);
         }
+        const extractor = new PhotonDocExtractor(photonPath);
+        const diagram = await extractor.generateDiagram();
+        // Output just the diagram (can be piped or copied)
+        console.log(diagram);
     }
     catch (error) {
-        console.error(`❌ Error: ${error.message}`);
-        process.exit(1);
-    }
-});
-// Add command: add MCP from marketplace
-program
-    .command('add', { hidden: true })
-    .argument('<name>', 'MCP name to add')
-    .option('--marketplace <name>', 'Specific marketplace to use')
-    .option('-y, --yes', 'Automatically select first suggestion without prompting')
-    .description('Add an MCP from a marketplace')
-    .action(async (name, options, command) => {
-    try {
-        // Get working directory from global options
-        const workingDir = command.parent?.opts().dir || DEFAULT_WORKING_DIR;
-        await ensureWorkingDir(workingDir);
-        const { MarketplaceManager } = await import('./marketplace-manager.js');
-        const manager = new MarketplaceManager();
-        await manager.initialize();
-        // Check for conflicts
-        let conflict = await manager.checkConflict(name, options.marketplace);
-        if (!conflict.sources || conflict.sources.length === 0) {
-            console.error(`❌ MCP '${name}' not found in any enabled marketplace\n`);
-            // Search for similar names
-            const searchResults = await manager.search(name);
-            if (searchResults.size > 0) {
-                console.error(`Did you mean one of these?\n`);
-                // Convert search results to array for selection
-                const suggestions = [];
-                let count = 0;
-                for (const [mcpName, sources] of searchResults) {
-                    if (count >= 5)
-                        break; // Limit to 5 suggestions
-                    const source = sources[0]; // Use first marketplace
-                    const version = source.metadata?.version || 'unknown';
-                    const description = source.metadata?.description || 'No description';
-                    suggestions.push({ name: mcpName, version, description });
-                    console.error(`  [${count + 1}] ${mcpName} (v${version})`);
-                    console.error(`      ${description}`);
-                    count++;
-                }
-                // Interactive selection or auto-select with -y
-                let selectedIndex;
-                if (options.yes) {
-                    // Auto-select first suggestion
-                    selectedIndex = 0;
-                }
-                else {
-                    // Interactive selection
-                    selectedIndex = await new Promise((resolve) => {
-                        const rl = readline.createInterface({
-                            input: process.stdin,
-                            output: process.stderr,
-                        });
-                        const askQuestion = () => {
-                            rl.question(`\nWhich one? [1-${suggestions.length}] (or press Enter to cancel): `, (answer) => {
-                                const trimmed = answer.trim();
-                                // Empty input = cancel
-                                if (trimmed === '') {
-                                    rl.close();
-                                    resolve(null);
-                                    return;
-                                }
-                                const choice = parseInt(trimmed, 10);
-                                // Validate input
-                                if (isNaN(choice) || choice < 1 || choice > suggestions.length) {
-                                    console.error(`Invalid choice. Please enter a number between 1 and ${suggestions.length}.`);
-                                    askQuestion();
-                                }
-                                else {
-                                    rl.close();
-                                    resolve(choice - 1);
-                                }
-                            });
-                        };
-                        askQuestion();
-                    });
-                    if (selectedIndex === null) {
-                        console.error('\nCancelled.');
-                        process.exit(0);
-                    }
-                }
-                // Update name to the selected MCP
-                name = suggestions[selectedIndex].name;
-                console.error(`\n✓ Selected: ${name}`);
-                // Re-check for conflicts with the new name
-                conflict = await manager.checkConflict(name, options.marketplace);
-                if (!conflict.sources || conflict.sources.length === 0) {
-                    console.error(`❌ MCP '${name}' is no longer available`);
-                    process.exit(1);
-                }
-            }
-            else {
-                console.error(`Run 'photon info' to see all available MCPs`);
-                process.exit(1);
-            }
-        }
-        // Check if already exists locally
-        const filePath = path.join(workingDir, `${name}.photon.ts`);
-        const fileName = `${name}.photon.ts`;
-        if (existsSync(filePath)) {
-            console.error(`⚠️  MCP '${name}' already exists`);
-            console.error(`Use 'photon upgrade ${name}' to update it`);
-            process.exit(1);
-        }
-        // Handle conflicts
-        let selectedMarketplace;
-        let selectedMetadata;
-        if (conflict.hasConflict) {
-            console.error(`⚠️  MCP '${name}' found in multiple marketplaces:\n`);
-            conflict.sources.forEach((source, index) => {
-                const marker = source.marketplace.name === conflict.recommendation ? '→' : ' ';
-                const version = source.metadata?.version || 'unknown';
-                console.error(`  ${marker} [${index + 1}] ${source.marketplace.name} (v${version})`);
-                console.error(`      ${source.marketplace.repo || source.marketplace.url}`);
-            });
-            if (conflict.recommendation) {
-                console.error(`\n💡 Recommended: ${conflict.recommendation} (newest version)`);
-            }
-            // Get default choice (recommended or first)
-            const recommendedIndex = conflict.sources.findIndex(s => s.marketplace.name === conflict.recommendation);
-            const defaultChoice = recommendedIndex !== -1 ? recommendedIndex + 1 : 1;
-            // Interactive selection
-            const selectedIndex = await new Promise((resolve) => {
-                const rl = readline.createInterface({
-                    input: process.stdin,
-                    output: process.stderr,
-                });
-                const askQuestion = () => {
-                    rl.question(`\nWhich marketplace? [1-${conflict.sources.length}] (default: ${defaultChoice}): `, (answer) => {
-                        const trimmed = answer.trim();
-                        // Empty input = use default
-                        if (trimmed === '') {
-                            rl.close();
-                            resolve(defaultChoice - 1);
-                            return;
-                        }
-                        const choice = parseInt(trimmed, 10);
-                        // Validate input
-                        if (isNaN(choice) || choice < 1 || choice > conflict.sources.length) {
-                            console.error(`Invalid choice. Please enter a number between 1 and ${conflict.sources.length}.`);
-                            askQuestion();
-                        }
-                        else {
-                            rl.close();
-                            resolve(choice - 1);
-                        }
-                    });
-                };
-                askQuestion();
-            });
-            const selectedSource = conflict.sources[selectedIndex];
-            selectedMarketplace = selectedSource.marketplace;
-            selectedMetadata = selectedSource.metadata;
-            console.error(`\n✓ Using: ${selectedMarketplace.name}`);
-        }
-        else {
-            selectedMarketplace = conflict.sources[0].marketplace;
-            selectedMetadata = conflict.sources[0].metadata;
-            console.error(`Adding ${name} from ${selectedMarketplace.name}...`);
-        }
-        // Fetch content from selected marketplace
-        const result = await manager.fetchMCP(name);
-        if (!result) {
-            console.error(`❌ Failed to fetch MCP content`);
-            process.exit(1);
-        }
-        const content = result.content;
-        // Write file
-        await fs.writeFile(filePath, content, 'utf-8');
-        // Save installation metadata if we have it
-        if (selectedMetadata) {
-            const { calculateHash } = await import('./marketplace-manager.js');
-            const contentHash = calculateHash(content);
-            await manager.savePhotonMetadata(fileName, selectedMarketplace, selectedMetadata, contentHash);
-        }
-        console.error(`✅ Added ${name} from ${selectedMarketplace.name}`);
-        if (selectedMetadata?.version) {
-            console.error(`Version: ${selectedMetadata.version}`);
+        logger.error(`Error: ${getErrorMessage(error)}`);
+        if (process.env.DEBUG && error instanceof Error) {
+            console.error(error.stack);
         }
-        console.error(`Location: ${filePath}`);
-        console.error(`\nRun with: photon mcp ${name}`);
-        console.error(`\nTo customize: Copy to a new name and run with --dev for hot reload`);
-    }
-    catch (error) {
-        console.error(`❌ Error: ${error.message}`);
         process.exit(1);
     }
 });
-// Remove command: remove an installed photon
-program
-    .command('remove', { hidden: true })
-    .argument('<name>', 'MCP name to remove')
-    .alias('rm')
-    .option('--keep-cache', 'Keep compiled cache for this photon')
-    .description('Remove an installed photon')
-    .action(async (name, options, command) => {
+// maker diagrams: generate Mermaid diagrams for all Photons in a directory
+maker
+    .command('diagrams')
+    .option('--dir <path>', 'Directory to scan (defaults to current directory)')
+    .description('Generate Mermaid diagrams for all Photons in a directory')
+    .action(async (options) => {
     try {
-        const { printInfo, printSuccess, printError } = await import('./cli-formatter.js');
-        const workingDir = command.parent?.opts().dir || DEFAULT_WORKING_DIR;
-        // Find the photon file
-        const filePath = await resolvePhotonPath(name, workingDir);
-        if (!filePath) {
-            printError(`Photon not found: ${name}`);
-            printInfo(`Searched in: ${workingDir}`);
-            printInfo(`Tip: Use 'photon info' to see installed photons`);
+        const { PhotonDocExtractor } = await import('./photon-doc-extractor.js');
+        const dirPath = path.resolve(options.dir || '.');
+        const files = await fs.readdir(dirPath);
+        const photonFiles = files.filter((f) => f.endsWith('.photon.ts'));
+        if (photonFiles.length === 0) {
+            console.error('No .photon.ts files found');
             process.exit(1);
         }
-        printInfo(`Removing ${name}...`);
-        // Remove the .photon.ts file
-        await fs.unlink(filePath);
-        printSuccess(`Removed ${name}.photon.ts`);
-        // Clear compiled cache unless --keep-cache
-        if (!options.keepCache) {
-            const cacheDir = path.join(os.homedir(), '.cache', 'photon-mcp', 'compiled');
-            const cachedFiles = [
-                path.join(cacheDir, `${name}.js`),
-                path.join(cacheDir, `${name}.js.map`),
-            ];
-            for (const cachedFile of cachedFiles) {
-                try {
-                    await fs.unlink(cachedFile);
-                }
-                catch {
-                    // Ignore if cache doesn't exist
-                }
-            }
-            printSuccess(`Cleared cache`);
-        }
-        console.log('');
-        printSuccess(`Successfully removed ${name}`);
-        printInfo(`To reinstall: photon add ${name}`);
-    }
-    catch (error) {
-        const { printError } = await import('./cli-formatter.js');
-        printError(error.message);
-        process.exit(1);
-    }
-});
-// Upgrade command: update MCPs from marketplace
-program
-    .command('upgrade', { hidden: true })
-    .argument('[name]', 'MCP name to upgrade (upgrades all if omitted)')
-    .option('--check', 'Check for updates without upgrading')
-    .alias('up')
-    .description('Upgrade MCP(s) from marketplaces')
-    .action(async (name, options, command) => {
-    try {
-        const { formatOutput, printInfo, printSuccess, printWarning, printError, STATUS } = await import('./cli-formatter.js');
-        // Get working directory from global options
-        const workingDir = command.parent?.opts().dir || DEFAULT_WORKING_DIR;
-        const { VersionChecker } = await import('./version-checker.js');
-        const checker = new VersionChecker();
-        await checker.initialize();
-        if (name) {
-            // Upgrade single MCP
-            const filePath = await resolvePhotonPath(name, workingDir);
-            if (!filePath) {
-                printError(`MCP not found: ${name}`);
-                printInfo(`Searched in: ${workingDir}`);
-                process.exit(1);
-            }
-            printInfo(`Checking ${name} for updates...`);
-            const versionInfo = await checker.checkForUpdate(name, filePath);
-            if (!versionInfo.local) {
-                printWarning('Could not determine local version');
-                return;
-            }
-            if (!versionInfo.remote) {
-                printWarning('Not found in any marketplace. This might be a local-only MCP.');
-                return;
-            }
-            if (options.check) {
-                const tableData = [{
-                        name,
-                        local: versionInfo.local,
-                        remote: versionInfo.remote,
-                        status: versionInfo.needsUpdate ? STATUS.UPDATE : STATUS.OK,
-                    }];
-                formatOutput(tableData, 'table');
-                return;
-            }
-            if (!versionInfo.needsUpdate) {
-                printSuccess(`Already up to date (${versionInfo.local})`);
-                return;
-            }
-            printInfo(`Upgrading ${name}: ${versionInfo.local} → ${versionInfo.remote}`);
-            const success = await checker.updateMCP(name, filePath);
-            if (success) {
-                printSuccess(`Successfully upgraded ${name} to ${versionInfo.remote}`);
-            }
-            else {
-                printError(`Failed to upgrade ${name}`);
-                process.exit(1);
-            }
-        }
-        else {
-            // Check/upgrade all MCPs
-            printInfo(`Checking all MCPs in ${workingDir}...\n`);
-            const updates = await checker.checkAllUpdates(workingDir);
-            if (updates.size === 0) {
-                printInfo('No MCPs found');
-                return;
-            }
-            const needsUpdate = [];
-            // Build table data
-            const tableData = [];
-            for (const [mcpName, info] of updates) {
-                if (info.needsUpdate) {
-                    needsUpdate.push(mcpName);
-                    tableData.push({
-                        name: mcpName,
-                        local: info.local || '-',
-                        remote: info.remote || '-',
-                        status: STATUS.UPDATE,
-                    });
-                }
-                else if (info.local && info.remote) {
-                    tableData.push({
-                        name: mcpName,
-                        local: info.local,
-                        remote: info.remote,
-                        status: STATUS.OK,
-                    });
-                }
-                else {
-                    tableData.push({
-                        name: mcpName,
-                        local: info.local || '-',
-                        remote: info.remote || 'local only',
-                        status: STATUS.UNKNOWN,
-                    });
-                }
-            }
-            formatOutput(tableData, 'table');
-            if (needsUpdate.length === 0) {
-                console.log('');
-                printSuccess('All MCPs are up to date!');
-                return;
-            }
-            if (options.check) {
-                console.log('');
-                printInfo(`${needsUpdate.length} MCP(s) have updates available`);
-                printInfo(`Run 'photon upgrade' to upgrade all`);
-                return;
-            }
-            // Upgrade all that need updates
-            console.log('');
-            printInfo(`Upgrading ${needsUpdate.length} MCP(s)...`);
-            for (const mcpName of needsUpdate) {
-                const filePath = path.join(workingDir, `${mcpName}.photon.ts`);
-                const success = await checker.updateMCP(mcpName, filePath);
-                if (success) {
-                    printSuccess(`Upgraded ${mcpName}`);
-                }
-                else {
-                    printError(`Failed to upgrade ${mcpName}`);
-                }
-            }
-        }
-    }
-    catch (error) {
-        const { printError } = await import('./cli-formatter.js');
-        printError(error.message);
-        process.exit(1);
-    }
-});
-// Clear-cache command: clear compiled photon cache
-program
-    .command('clear-cache', { hidden: true })
-    .argument('[name]', 'MCP name to clear cache for (clears all if omitted)')
-    .alias('clean')
-    .description('Clear compiled photon cache')
-    .action(async (name, options, command) => {
-    try {
-        const { printInfo, printSuccess, printError } = await import('./cli-formatter.js');
-        const cacheDir = path.join(os.homedir(), '.cache', 'photon-mcp', 'compiled');
-        if (name) {
-            // Clear cache for specific photon
-            const workingDir = command.parent?.opts().dir || DEFAULT_WORKING_DIR;
-            const filePath = await resolvePhotonPath(name, workingDir);
-            if (!filePath) {
-                printError(`Photon not found: ${name}`);
-                printInfo(`Tip: Use 'photon info' to see installed photons`);
-                process.exit(1);
-            }
-            printInfo(`Clearing cache for ${name}...`);
-            const cachedFiles = [
-                path.join(cacheDir, `${name}.js`),
-                path.join(cacheDir, `${name}.js.map`),
-            ];
-            let cleared = false;
-            for (const cachedFile of cachedFiles) {
-                try {
-                    await fs.unlink(cachedFile);
-                    cleared = true;
-                }
-                catch {
-                    // Ignore if file doesn't exist
-                }
-            }
-            if (cleared) {
-                printSuccess(`Cleared cache for ${name}`);
-            }
-            else {
-                printInfo(`No cache found for ${name}`);
-            }
-        }
-        else {
-            // Clear all cache
-            printInfo('Clearing all compiled photon cache...');
+        console.error(`📦 Found ${photonFiles.length} photons\n`);
+        for (const file of photonFiles) {
+            const photonPath = path.join(dirPath, file);
+            const name = file.replace('.photon.ts', '');
             try {
-                const files = await fs.readdir(cacheDir);
-                let count = 0;
-                for (const file of files) {
-                    const filePath = path.join(cacheDir, file);
-                    try {
-                        await fs.unlink(filePath);
-                        count++;
-                    }
-                    catch {
-                        // Ignore errors
-                    }
-                }
-                if (count > 0) {
-                    printSuccess(`Cleared ${count} cached file(s)`);
-                }
-                else {
-                    printInfo(`Cache is already empty`);
-                }
+                const extractor = new PhotonDocExtractor(photonPath);
+                const diagram = await extractor.generateDiagram();
+                console.log(`## ${name}\n`);
+                console.log('```mermaid');
+                console.log(diagram);
+                console.log('```\n');
             }
-            catch (error) {
-                if (error.code === 'ENOENT') {
-                    printInfo(`No cache directory found`);
-                }
-                else {
-                    throw error;
-                }
+            catch (err) {
+                console.error(`⚠️  Failed to generate diagram for ${name}: ${err.message}`);
             }
         }
     }
     catch (error) {
-        const { printError } = await import('./cli-formatter.js');
-        printError(error.message);
+        logger.error(`Error: ${getErrorMessage(error)}`);
+        if (process.env.DEBUG && error instanceof Error) {
+            console.error(error.stack);
+        }
         process.exit(1);
     }
 });
+// Register marketplace commands (list, add, remove, enable, disable)
+registerMarketplaceCommands(program);
+// Register info command
+registerInfoCommand(program, DEFAULT_WORKING_DIR);
+// Register package management commands
+registerPackageCommands(program, DEFAULT_WORKING_DIR);
+// Register package-app command (cross-platform PWA launchers)
+registerPackageAppCommand(program, DEFAULT_WORKING_DIR);
 // Doctor command: diagnose photon environment
 program
-    .command('doctor', { hidden: true })
+    .command('doctor')
     .argument('[name]', 'Photon name to diagnose (checks environment if omitted)')
-    .description('Run diagnostics on photon environment and installations')
+    .description('Run diagnostics on photon environment, ports, and configuration')
+    .option('--port <number>', 'Port to check for availability', '3000')
     .action(async (name, options, command) => {
     try {
-        const { formatOutput, printInfo, printSuccess, printWarning, STATUS } = await import('./cli-formatter.js');
+        const { formatOutput, printHeader, printInfo, printSuccess, printWarning, STATUS } = await import('./cli-formatter.js');
         const workingDir = command.parent?.opts().dir || DEFAULT_WORKING_DIR;
-        let issuesFound = 0;
-        printInfo('Running Photon diagnostics...\n');
-        // Build diagnostic data
         const diagnostics = {};
-        // Check Node version
+        const suggestions = [];
+        let issuesFound = 0;
+        printHeader('Photon Doctor');
+        printInfo('Running environment checks...\n');
+        // Node runtime
         const nodeVersion = process.version;
         const majorVersion = parseInt(nodeVersion.slice(1).split('.')[0]);
         diagnostics['Node.js'] = {
             version: nodeVersion,
             status: majorVersion >= 18 ? STATUS.OK : STATUS.ERROR,
-            note: majorVersion >= 18 ? 'supported' : 'requires Node.js 18+',
         };
-        if (majorVersion < 18)
+        if (majorVersion < 18) {
             issuesFound++;
-        // Check npm/npx
+            suggestions.push('Upgrade to Node.js 18+ (https://nodejs.org).');
+        }
+        // npm availability
         try {
             const { execSync } = await import('child_process');
             const npmVersion = execSync('npm --version', { encoding: 'utf-8' }).trim();
-            diagnostics['Package Manager'] = {
-                npm: npmVersion,
-                status: STATUS.OK,
-            };
+            diagnostics['Package manager'] = { npm: npmVersion, status: STATUS.OK };
         }
         catch {
-            diagnostics['Package Manager'] = {
-                npm: 'not found',
-                status: STATUS.ERROR,
-            };
+            diagnostics['Package manager'] = { npm: 'not found', status: STATUS.ERROR };
             issuesFound++;
+            suggestions.push('Install npm / npx so Photon can install dependencies.');
         }
-        // Check working directory
+        // Working directory health
         try {
             await fs.access(workingDir);
             const stats = await fs.stat(workingDir);
             if (stats.isDirectory()) {
                 const mcps = await listPhotonMCPs(workingDir);
-                diagnostics['Working Directory'] = {
+                diagnostics['Working directory'] = {
                     path: workingDir,
                     status: STATUS.OK,
                     photons: mcps.length,
                 };
             }
             else {
-                diagnostics['Working Directory'] = {
+                diagnostics['Working directory'] = {
                     path: workingDir,
                     status: STATUS.ERROR,
-                    note: 'not a directory',
+                    note: 'Not a directory',
                 };
                 issuesFound++;
+                suggestions.push(`Fix working directory: rm ${workingDir} && mkdir -p ${workingDir}`);
             }
         }
         catch {
-            diagnostics['Working Directory'] = {
+            diagnostics['Working directory'] = {
                 path: workingDir,
-                status: STATUS.UNKNOWN,
-                note: 'will be created on first use',
+                status: STATUS.WARN,
+                note: 'Will be created on first use',
             };
         }
-        // Check cache directory
+        // Cache directory insight
         const cacheDir = path.join(os.homedir(), '.cache', 'photon-mcp', 'compiled');
         try {
             await fs.access(cacheDir);
             const files = await fs.readdir(cacheDir);
-            diagnostics['Cache Directory'] = {
+            diagnostics['Cache directory'] = {
                 path: cacheDir,
                 status: STATUS.OK,
                 cachedFiles: files.length,
             };
         }
         catch {
-            diagnostics['Cache Directory'] = {
+            diagnostics['Cache directory'] = {
                 path: cacheDir,
                 status: STATUS.UNKNOWN,
-                note: 'will be created on first use',
+                note: 'Created on demand',
             };
         }
-        // Check marketplaces and conflicts
-        let manager;
+        // Port availability
+        const port = parseInt(options.port, 10);
+        const available = await isPortAvailable(port);
+        diagnostics['Ports'] = {
+            port,
+            status: available ? STATUS.OK : STATUS.ERROR,
+            note: available ? 'Available' : 'In use by another process',
+        };
+        if (!available) {
+            issuesFound++;
+            suggestions.push(`Port ${port} is busy. Run Photon with '--port ${port + 1}' or stop the conflicting service.`);
+        }
+        // Marketplace configuration
         try {
             const { MarketplaceManager } = await import('./marketplace-manager.js');
-            manager = new MarketplaceManager();
+            const manager = new MarketplaceManager();
             await manager.initialize();
-            const marketplaces = manager.getAll();
-            const enabled = marketplaces.filter((m) => m.enabled);
-            if (enabled.length > 0) {
-                // Check for conflicts
-                const conflicts = await manager.detectAllConflicts();
-                if (conflicts.size > 0) {
-                    diagnostics['Marketplaces'] = {
-                        enabled: enabled.length,
-                        status: STATUS.WARN,
-                        sources: enabled.map((m) => m.name),
-                        conflicts: `${conflicts.size} photon(s) in multiple marketplaces`,
-                    };
-                    issuesFound++;
-                }
-                else {
-                    diagnostics['Marketplaces'] = {
-                        enabled: enabled.length,
-                        status: STATUS.OK,
-                        sources: enabled.map((m) => m.name),
-                    };
-                }
+            const enabled = manager.getAll().filter((m) => m.enabled);
+            if (enabled.length === 0) {
+                diagnostics['Marketplaces'] = {
+                    status: STATUS.WARN,
+                    note: 'No marketplaces configured. Add one with: photon marketplace add portel-dev/photons',
+                };
+                suggestions.push('Add at least one marketplace so you can install community photons.');
             }
             else {
+                const conflicts = await manager.detectAllConflicts();
                 diagnostics['Marketplaces'] = {
-                    enabled: 0,
-                    status: STATUS.UNKNOWN,
-                    note: 'Add one with: photon marketplace add portel-dev/photons',
+                    status: conflicts.size > 0 ? STATUS.WARN : STATUS.OK,
+                    enabled: enabled.map((m) => m.name),
+                    conflicts: conflicts.size,
                 };
+                if (conflicts.size > 0) {
+                    issuesFound++;
+                    suggestions.push('Resolve duplicate photons with: photon marketplace resolve');
+                }
             }
         }
         catch (error) {
-            diagnostics['Marketplaces'] = {
-                status: STATUS.ERROR,
-                error: error.message,
-            };
+            diagnostics['Marketplaces'] = { status: STATUS.ERROR, error: getErrorMessage(error) };
+            suggestions.push('Marketplace config failed to load. Run photon marketplace list to debug.');
             issuesFound++;
         }
-        // Check specific photon if provided
+        // Photon-specific checks
         if (name) {
-            const photonDiag = {};
+            const photonSection = {};
             const filePath = await resolvePhotonPath(name, workingDir);
             if (!filePath) {
-                photonDiag['location'] = 'not found';
-                photonDiag['status'] = STATUS.ERROR;
+                photonSection.status = STATUS.ERROR;
+                photonSection.note = `Not installed in ${workingDir}`;
+                suggestions.push(`Install ${name} with: photon add ${name}`);
                 issuesFound++;
             }
             else {
-                photonDiag['location'] = filePath;
-                photonDiag['status'] = STATUS.OK;
-                // Check if it compiles
-                try {
-                    const source = await fs.readFile(filePath, 'utf-8');
-                    const extractor = new SchemaExtractor();
-                    const params = extractor.extractConstructorParams(source);
-                    photonDiag['syntax'] = STATUS.OK;
-                    photonDiag['constructorParams'] = params.length;
-                }
-                catch (error) {
-                    photonDiag['syntax'] = STATUS.ERROR;
-                    photonDiag['syntaxError'] = error.message;
-                    issuesFound++;
+                photonSection.status = STATUS.OK;
+                photonSection.path = filePath;
+                const params = await extractConstructorParams(filePath);
+                if (params.length > 0) {
+                    photonSection.environment = params.map((param) => {
+                        const envVar = toEnvVarName(name, param.name);
+                        const value = process.env[envVar];
+                        const ok = Boolean(value) || param.isOptional || param.hasDefault;
+                        if (!ok) {
+                            issuesFound++;
+                            suggestions.push(`Set ${envVar} for ${name} (e.g. export ${envVar}=value).`);
+                        }
+                        return {
+                            name: envVar,
+                            status: ok ? STATUS.OK : STATUS.ERROR,
+                            value: value
+                                ? 'configured'
+                                : param.hasDefault
+                                    ? `default: ${formatDefaultValue(param.defaultValue)}`
+                                    : 'missing',
+                        };
+                    });
                 }
-                // Check cache
                 const cachedFile = path.join(cacheDir, `${name}.js`);
                 try {
                     await fs.access(cachedFile);
-                    photonDiag['cache'] = STATUS.OK;
+                    photonSection.cache = { status: STATUS.OK, note: 'Warm' };
                 }
                 catch {
-                    photonDiag['cache'] = 'not cached yet';
-                }
-                // Check dependencies and security
-                try {
-                    const { DependencyManager } = await import('@portel/photon-core');
-                    const depManager = new DependencyManager();
-                    const dependencies = await depManager.extractDependencies(filePath);
-                    if (dependencies.length > 0) {
-                        photonDiag['dependencies'] = dependencies.map(dep => `${dep.name}@${dep.version}`);
-                        // Security audit
-                        try {
-                            const { SecurityScanner } = await import('./security-scanner.js');
-                            const scanner = new SecurityScanner();
-                            const depStrings = dependencies.map(d => `${d.name}@${d.version}`);
-                            const result = await scanner.auditMCP(name, depStrings);
-                            if (result.totalVulnerabilities > 0) {
-                                photonDiag['security'] = STATUS.ERROR;
-                                photonDiag['vulnerabilities'] = `${result.totalVulnerabilities} (${result.criticalCount} critical, ${result.highCount} high)`;
-                                issuesFound++;
-                            }
-                            else {
-                                photonDiag['security'] = STATUS.OK;
-                            }
-                        }
-                        catch {
-                            photonDiag['security'] = 'could not check';
-                        }
-                    }
-                    else {
-                        photonDiag['dependencies'] = 'none';
-                        photonDiag['security'] = STATUS.OK;
-                    }
-                }
-                catch (error) {
-                    photonDiag['dependencies'] = `error: ${error.message}`;
+                    photonSection.cache = {
+                        status: STATUS.WARN,
+                        note: 'Not compiled yet (first run will compile)',
+                    };
                 }
             }
-            diagnostics[`Photon: ${name}`] = photonDiag;
+            diagnostics[`Photon: ${name}`] = photonSection;
         }
         formatOutput(diagnostics, 'tree');
-        // Summary
-        console.log('');
-        if (issuesFound === 0) {
-            printSuccess('No issues found! Photon environment is healthy.');
+        if (suggestions.length > 0) {
+            printHeader('Suggested fixes');
+            suggestions.forEach((tip, idx) => console.log(` ${idx + 1}. ${tip}`));
+        }
+        if (issuesFound === 0 && suggestions.length === 0) {
+            printSuccess('\nAll checks passed!');
         }
         else {
-            printWarning(`Found ${issuesFound} issue(s). Please address the items marked with '${STATUS.ERROR}' above.`);
-            process.exit(1);
+            printWarning(`\nDetected ${issuesFound || suggestions.length} potential issue(s).`);
         }
     }
     catch (error) {
         const { printError } = await import('./cli-formatter.js');
-        printError(error.message);
+        printError(getErrorMessage(error));
         process.exit(1);
     }
 });
 // CLI command: directly invoke photon methods
+// Also serves as escape hatch for photons with reserved names (e.g., photon cli list get)
 program
-    .command('cli <photon> [method] [args...]', { hidden: true })
-    .description('Run photon methods directly from the command line')
+    .command('cli <photon> [method] [args...]')
+    .description('Run photon methods from command line (escape hatch for reserved names)')
     .allowUnknownOption()
     .helpOption(false) // Disable default help so we can handle it ourselves
     .action(async (photon, method, args) => {
     // Handle help flag
     if (photon === '--help' || photon === '-h') {
         console.log(`USAGE:
-    photon cli <photon-name> [method] [args...]
+    photon <photon-name> [method] [args...]
+    photon cli <photon-name> [method] [args...]   (explicit form)
 
 DESCRIPTION:
     Run photon methods directly from the command line. Photons provide
     a CLI interface automatically based on their exported methods.
 
+    The 'cli' command is optional - you can run photons directly:
+      photon lg-remote volume +5      (implicit)
+      photon cli lg-remote volume +5  (explicit)
+
+    Use 'photon cli' explicitly when your photon name conflicts with
+    a reserved command (serve, beam, list, init, etc.)
+
 EXAMPLES:
     # List all methods for a photon
-    photon cli lg-remote
+    photon lg-remote
 
     # Call a method with no parameters
-    photon cli lg-remote status
+    photon lg-remote status
 
     # Call a method with parameters
-    photon cli lg-remote volume 50
-    photon cli lg-remote volume +5
-    photon cli lg-remote volume --level=-3
+    photon lg-remote volume 50
+    photon lg-remote volume +5
+    photon spotify play
 
     # Get method-specific help
-    photon cli lg-remote volume --help
+    photon lg-remote volume --help
 
     # Output raw JSON instead of formatted text
-    photon cli lg-remote status --json
+    photon lg-remote status --json
+
+    # Escape hatch for reserved-name photons
+    photon cli list get       (photon named "list", method "get")
+    photon cli serve status   (photon named "serve", method "status")
 
 SEE ALSO:
-    photon info           List all installed photons
+    photon list           List all installed photons
     photon add <name>     Install a photon from marketplace
-    photon alias          Create CLI shortcuts for photons
 `);
         return;
     }
@@ -1957,13 +1840,124 @@ program
     const { listAliases } = await import('./cli-alias.js');
     await listAliases();
 });
+// Test command: run tests for photons
+program
+    .command('test')
+    .argument('[photon]', 'Photon to test (tests all if omitted)')
+    .argument('[test]', 'Specific test to run')
+    .option('--json', 'Output results as JSON')
+    .option('--mode <mode>', 'Test mode: direct (unit), cli (integration via CLI), mcp (integration via MCP), all', 'direct')
+    .description('Run test methods in photons')
+    .action(async (photon, test, options) => {
+    try {
+        const workingDir = program.opts().dir || DEFAULT_WORKING_DIR;
+        const { runTests } = await import('./test-runner.js');
+        // Validate mode
+        const validModes = ['direct', 'cli', 'mcp', 'all'];
+        if (!validModes.includes(options.mode)) {
+            logger.error(`Invalid mode: ${options.mode}. Valid modes: ${validModes.join(', ')}`);
+            process.exit(1);
+        }
+        const summary = await runTests(workingDir, photon, test, {
+            json: options.json,
+            mode: options.mode,
+        });
+        // Exit with error code if any tests failed
+        if (summary.failed > 0) {
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        logger.error(`Error: ${getErrorMessage(error)}`);
+        process.exit(1);
+    }
+});
+// Reserved commands that should NOT be treated as photon names
+// Reserved commands that should NOT be treated as photon names
+// If first arg is not in this list, it's assumed to be a photon name (implicit CLI mode)
+const RESERVED_COMMANDS = [
+    // Core commands
+    'serve',
+    'sse',
+    'beam',
+    'list',
+    'ls',
+    'info',
+    'test',
+    // Photon management
+    'new',
+    'init',
+    'validate',
+    'sync',
+    'add',
+    'remove',
+    'rm',
+    // Maintenance
+    'upgrade',
+    'up',
+    'update',
+    'doctor',
+    'clear-cache',
+    'clean',
+    // Aliases
+    'cli',
+    'alias',
+    'unalias',
+    'aliases',
+    // Marketplace
+    'marketplace',
+    // Packaging
+    'package',
+    // Hidden/advanced
+    'mcp',
+    'search',
+    'maker',
+    'host',
+    'diagram',
+    'diagrams',
+    'enable',
+    'disable',
+    // Help/version (handled by commander)
+    'help',
+    '--help',
+    '-h',
+    'version',
+    '--version',
+    '-V',
+];
 // All known commands for "did you mean" suggestions
 const knownCommands = [
-    'mcp', 'info', 'list', 'ls', 'search',
-    'add', 'remove', 'rm', 'upgrade', 'up', 'update',
-    'clear-cache', 'clean', 'doctor',
-    'cli', 'alias', 'unalias', 'aliases',
-    'marketplace', 'maker',
+    'serve',
+    'sse',
+    'beam',
+    'list',
+    'ls',
+    'info',
+    'test',
+    'new',
+    'init',
+    'validate',
+    'sync',
+    'add',
+    'remove',
+    'rm',
+    'upgrade',
+    'up',
+    'update',
+    'clear-cache',
+    'clean',
+    'doctor',
+    'cli',
+    'alias',
+    'unalias',
+    'aliases',
+    'mcp',
+    'search',
+    'marketplace',
+    'maker',
+    'host',
+    'diagram',
+    'diagrams',
 ];
 const knownSubcommands = {
     marketplace: ['list', 'add', 'remove', 'enable', 'disable'],
@@ -2019,7 +2013,7 @@ program.on('command:*', async (operands) => {
     printError(`Unknown command: ${unknownCommand}`);
     // Check if it's a subcommand typo for a known parent
     const args = process.argv.slice(2);
-    const parentIndex = args.findIndex(arg => knownSubcommands[arg]);
+    const parentIndex = args.findIndex((arg) => knownSubcommands[arg]);
     if (parentIndex !== -1 && parentIndex < args.indexOf(unknownCommand)) {
         const parent = args[parentIndex];
         const suggestion = findClosestCommand(unknownCommand, knownSubcommands[parent]);
@@ -2038,7 +2032,48 @@ program.on('command:*', async (operands) => {
     printInfo(`Run 'photon --help' for usage`);
     process.exit(1);
 });
-program.parse();
+// ══════════════════════════════════════════════════════════════════════════════
+// IMPLICIT CLI MODE
+// ══════════════════════════════════════════════════════════════════════════════
+// If the first argument is not a reserved command, treat it as a photon name
+// This enables: `photon lg-remote volume +5` instead of `photon cli lg-remote volume +5`
+function preprocessArgs() {
+    const args = process.argv.slice(2);
+    // No args - default to beam with auto-open browser
+    if (args.length === 0) {
+        return [...process.argv, 'beam', '--open'];
+    }
+    // Find the first non-flag argument (skip values of flags that take a parameter)
+    const flagsWithValues = ['--dir', '--log-level'];
+    const firstArgIndex = args.findIndex((arg, i) => {
+        if (arg.startsWith('-'))
+            return false;
+        // Skip values of preceding flags (e.g., "." in "--dir .")
+        if (i > 0 && flagsWithValues.includes(args[i - 1]))
+            return false;
+        return true;
+    });
+    if (firstArgIndex === -1) {
+        // No subcommand — only flags present (e.g., --dir=. --log-level debug)
+        // photon --help / -h / --version / -V → show program help/version
+        if (args.some((a) => a === '--help' || a === '-h' || a === '--version' || a === '-V')) {
+            return process.argv;
+        }
+        // Otherwise default to beam (e.g., photon --dir=. → photon --dir=. beam --open)
+        return [...process.argv, 'beam', '--open'];
+    }
+    const firstArg = args[firstArgIndex];
+    // If first arg is a reserved command, let commander handle normally
+    if (RESERVED_COMMANDS.includes(firstArg)) {
+        return process.argv;
+    }
+    // First arg looks like a photon name - inject 'cli' command
+    // photon lg-remote volume +5 → photon cli lg-remote volume +5
+    const newArgs = [...process.argv];
+    newArgs.splice(2 + firstArgIndex, 0, 'cli');
+    return newArgs;
+}
+program.parse(preprocessArgs());
 /**
  * Inline template fallback
  */