@portel/photon 1.2.0 → 1.4.0

package/dist/cli.js

@@ -13,7 +13,7 @@ import * as readline from 'readline';
 import { PhotonServer } from './server.js';
 import { FileWatcher } from './watcher.js';
 import { resolvePhotonPath, listPhotonMCPs, ensureWorkingDir, DEFAULT_WORKING_DIR } from './path-resolver.js';
-import { SchemaExtractor } from './schema-extractor.js';
+import { SchemaExtractor } from '@portel/photon-core';
 import { createRequire } from 'module';
 import { fileURLToPath } from 'url';
 const require = createRequire(import.meta.url);
@@ -75,6 +75,7 @@ async function ensureGitignore(workingDir) {
  */
 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);
@@ -82,7 +83,22 @@ async function performMarketplaceSync(dirPath, options) {
     // Scan for .photon.ts files
     console.error('📦 Scanning for .photon.ts files...');
     const files = await fs.readdir(resolvedPath);
-    const 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 originalCount = photonFiles.length;
+        photonFiles = photonFiles.filter(f => {
+            const name = f.replace(/\.photon\.ts$/, '');
+            return !installedNames.has(name);
+        });
+        if (originalCount !== photonFiles.length) {
+            console.error(`   Filtered out ${originalCount - photonFiles.length} installed photons`);
+        }
+    }
     if (photonFiles.length === 0) {
         console.error(`❌ No .photon.ts files found in ${resolvedPath}`);
         process.exit(1);
@@ -177,6 +193,99 @@ async function performMarketplaceSync(dirPath, options) {
     console.error(`   • *.md (${photons.length} documentation files at root)`);
     console.error(`   • README.md (auto-generated table)`);
 }
+/**
+ * Initialize a marketplace with git hooks
+ */
+async function performMarketplaceInit(dirPath, options) {
+    const absolutePath = path.resolve(dirPath);
+    // Check if directory exists
+    if (!existsSync(absolutePath)) {
+        await fs.mkdir(absolutePath, { recursive: true });
+        console.error(`📁 Created directory: ${absolutePath}`);
+    }
+    // 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);
+    }
+    // Create .githooks directory
+    const hooksDir = path.join(absolutePath, '.githooks');
+    await fs.mkdir(hooksDir, { recursive: true });
+    // Create pre-commit hook
+    const preCommitHook = `#!/bin/bash
+# Pre-commit hook: Auto-sync marketplace manifest before commit
+# This ensures .marketplace/photons.json and .claude-plugin/ are always up-to-date
+
+# Check if any .photon.ts files or marketplace files are being committed
+if git diff --cached --name-only | grep -qE '\\.photon\\.ts$|\\.marketplace/|\\.claude-plugin/'; then
+  echo "🔄 Syncing marketplace manifest..."
+
+  # Run photon maker sync with --claude-code to generate plugin files
+  if photon maker sync --dir . --claude-code; then
+    # Stage the generated files
+    git add .marketplace/photons.json README.md *.md .claude-plugin/ 2>/dev/null
+    echo "✅ Marketplace and Claude Code plugin synced and staged"
+  else
+    echo "❌ Failed to sync marketplace"
+    exit 1
+  fi
+fi
+
+exit 0
+`;
+    const preCommitPath = path.join(hooksDir, 'pre-commit');
+    await fs.writeFile(preCommitPath, preCommitHook, { mode: 0o755 });
+    console.error('✅ Created .githooks/pre-commit');
+    // Create setup script
+    const setupScript = `#!/bin/bash
+# Setup script to install git hooks for this marketplace
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+HOOKS_DIR="$REPO_ROOT/.git/hooks"
+SOURCE_HOOKS="$REPO_ROOT/.githooks"
+
+echo "🔧 Installing git hooks for Photon marketplace..."
+
+# Copy pre-commit hook
+if [ -f "$SOURCE_HOOKS/pre-commit" ]; then
+  cp "$SOURCE_HOOKS/pre-commit" "$HOOKS_DIR/pre-commit"
+  chmod +x "$HOOKS_DIR/pre-commit"
+  echo "✅ Installed pre-commit hook (auto-syncs marketplace manifest)"
+else
+  echo "❌ pre-commit hook not found"
+  exit 1
+fi
+
+echo ""
+echo "✅ Git hooks installed successfully!"
+echo ""
+echo "The pre-commit hook will automatically run 'photon maker sync'"
+echo "whenever you commit changes to .photon.ts files."
+`;
+    const setupPath = path.join(hooksDir, 'setup.sh');
+    await fs.writeFile(setupPath, setupScript, { mode: 0o755 });
+    console.error('✅ Created .githooks/setup.sh');
+    // Install hooks to .git/hooks
+    const gitHooksDir = path.join(absolutePath, '.git', 'hooks');
+    const gitPreCommitPath = path.join(gitHooksDir, 'pre-commit');
+    await fs.writeFile(gitPreCommitPath, preCommitHook, { mode: 0o755 });
+    console.error('✅ Installed hooks to .git/hooks');
+    // Create .marketplace directory
+    const marketplaceDir = path.join(absolutePath, '.marketplace');
+    await fs.mkdir(marketplaceDir, { recursive: true });
+    console.error('✅ Created .marketplace directory');
+    // Run initial sync (don't filter installed for marketplace repos)
+    console.error('\n🔄 Running initial marketplace sync...\n');
+    await performMarketplaceSync(absolutePath, options);
+    console.error('\n✅ Marketplace initialized successfully!');
+    console.error('\nNext steps:');
+    console.error('1. Add your .photon.ts files to this directory');
+    console.error('2. Commit your changes (hooks will auto-sync)');
+    console.error('3. Push to GitHub to share your marketplace');
+    console.error('\nContributors can setup hooks with:');
+    console.error('  bash .githooks/setup.sh');
+}
 /**
  * Format default value for display in config
  */
@@ -185,7 +294,8 @@ function formatDefaultValue(value) {
         // Check if it's a function call expression
         if (value.includes('homedir()')) {
             // Replace homedir() with actual home directory
-            return value.replace(/join\(homedir\(\),\s*['"]([^'"]+)['"]\)/g, (_, folderName) => {
+            // Handle both path.join() and join()
+            return value.replace(/(?:path\.)?join\(homedir\(\),\s*['"]([^'"]+)['"]\)/g, (_, folderName) => {
                 return path.join(os.homedir(), folderName);
             });
         }
@@ -316,7 +426,7 @@ async function validateConfiguration(filePath, mcpName) {
 /**
  * Show configuration template for an MCP
  */
-async function showConfigTemplate(filePath, mcpName) {
+async function showConfigTemplate(filePath, mcpName, workingDir = DEFAULT_WORKING_DIR) {
     console.log(`📋 Configuration template for: ${mcpName}\n`);
     const params = await extractConstructorParams(filePath);
     if (params.length === 0) {
@@ -345,11 +455,14 @@ async function showConfigTemplate(filePath, mcpName) {
             envExample[envVarName] = `<your-${param.name}>`;
         }
     });
+    const needsWorkingDir = workingDir !== DEFAULT_WORKING_DIR;
     const config = {
         mcpServers: {
             [mcpName]: {
                 command: 'npx',
-                args: ['@portel/photon', 'mcp', mcpName],
+                args: needsWorkingDir
+                    ? ['@portel/photon', 'mcp', mcpName, '--dir', workingDir]
+                    : ['@portel/photon', 'mcp', mcpName],
                 env: envExample,
             },
         },
@@ -373,10 +486,94 @@ program
     .name('photon')
     .description('Universal runtime for single-file TypeScript programs')
     .version(version)
-    .option('--working-dir <dir>', 'Working directory for Photons (default: ~/.photon)', DEFAULT_WORKING_DIR);
+    .option('--dir <path>', 'Photon directory (default: ~/.photon)', DEFAULT_WORKING_DIR)
+    .configureHelp({
+    sortSubcommands: false,
+    sortOptions: false,
+})
+    .addHelpText('after', `
+Runtime Commands:
+  mcp <name>              Run a photon as MCP server (for AI assistants)
+  cli <photon> [method]   Run photon methods from command line
+
+Package Management:
+  add <name>              Install a photon from marketplace
+  remove <name>           Remove an installed photon
+  upgrade [name]          Upgrade photon(s) to latest version
+  search <query>          Search marketplaces for photons
+  info [name]             Show installed photons and details
+
+Maintenance:
+  update                  Refresh marketplace indexes & check CLI version
+  doctor [name]           Diagnose environment and installations
+
+Development:
+  maker new <name>        Create a new photon from template
+  maker validate <name>   Validate photon syntax and schemas
+  maker sync              Generate marketplace manifest
+  maker init              Initialize marketplace with git hooks
+
+Advanced:
+  marketplace             Manage marketplace sources
+  alias <photon>          Create CLI shortcuts for photons
+
+Run 'photon <command> --help' for detailed usage.
+`);
+// Update command: refresh marketplace indexes and check for CLI updates
+program
+    .command('update', { hidden: true })
+    .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 { MarketplaceManager } = await import('./marketplace-manager.js');
+        const manager = new MarketplaceManager();
+        await manager.initialize();
+        const results = await manager.updateAllCaches();
+        for (const [marketplaceName, success] of results) {
+            if (success) {
+                printSuccess(`${marketplaceName}`);
+            }
+            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...');
+        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}`);
+                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);
+        process.exit(1);
+    }
+});
 // MCP Runtime: run a .photon.ts file as MCP server
 program
-    .command('mcp')
+    .command('mcp', { hidden: true })
     .argument('<name>', 'MCP name (without .photon.ts extension)')
     .description('Run a Photon as MCP server')
     .option('--dev', 'Enable development mode with hot reload')
@@ -385,7 +582,7 @@ program
     .action(async (name, options, command) => {
     try {
         // Get working directory from global options
-        const workingDir = program.opts().workingDir || DEFAULT_WORKING_DIR;
+        const workingDir = program.opts().dir || DEFAULT_WORKING_DIR;
         // Resolve file path from name in working directory
         const filePath = await resolvePhotonPath(name, workingDir);
         if (!filePath) {
@@ -401,7 +598,7 @@ program
         }
         // Handle --config flag
         if (options.config) {
-            await showConfigTemplate(filePath, name);
+            await showConfigTemplate(filePath, name, workingDir);
             return;
         }
         // Start MCP server
@@ -437,103 +634,20 @@ program
         process.exit(1);
     }
 });
-// Init command: create a new .photon.ts from template
-program
-    .command('init')
-    .argument('<name>', 'Name for the new Photon MCP')
-    .description('Create a new .photon.ts from template')
-    .action(async (name, options, command) => {
-    try {
-        // Get working directory from global options
-        const workingDir = command.parent?.opts().workingDir || DEFAULT_WORKING_DIR;
-        // Ensure working directory exists
-        await ensureWorkingDir(workingDir);
-        const fileName = `${name}.photon.ts`;
-        const filePath = path.join(workingDir, fileName);
-        // Check if file already exists
-        try {
-            await fs.access(filePath);
-            console.error(`❌ File already exists: ${filePath}`);
-            process.exit(1);
-        }
-        catch {
-            // File doesn't exist, good
-        }
-        // Read template
-        const templatePath = path.join(__dirname, '..', 'templates', 'photon.template.ts');
-        let template;
-        try {
-            template = await fs.readFile(templatePath, 'utf-8');
-        }
-        catch {
-            // Fallback inline template if file not found
-            template = getInlineTemplate();
-        }
-        // Replace placeholders
-        // Convert kebab-case to PascalCase for class name
-        const className = name
-            .split(/[-_]/)
-            .map(word => word.charAt(0).toUpperCase() + word.slice(1))
-            .join('');
-        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}`);
-        process.exit(1);
-    }
-});
-// Validate command: check syntax and schemas
-program
-    .command('validate')
-    .argument('<name>', 'MCP name (without .photon.ts extension)')
-    .description('Validate syntax and schemas without running')
-    .action(async (name, options, command) => {
-    try {
-        // Get working directory from global options
-        const workingDir = command.parent?.opts().workingDir || DEFAULT_WORKING_DIR;
-        // Resolve file path from name in working directory
-        const filePath = await resolvePhotonPath(name, workingDir);
-        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);
-        }
-        console.error(`Validating ${path.basename(filePath)}...\n`);
-        // Import loader and try to load
-        const { PhotonLoader } = await import('./loader.js');
-        const loader = new PhotonLoader(false); // quiet mode for inspection
-        const mcp = await loader.loadFile(filePath);
-        console.error(`✅ Valid Photon MCP`);
-        console.error(`Name: ${mcp.name}`);
-        console.error(`Tools: ${mcp.tools.length}`);
-        for (const tool of mcp.tools) {
-            console.error(`  - ${tool.name}: ${tool.description}`);
-        }
-        process.exit(0);
-    }
-    catch (error) {
-        console.error(`❌ Validation failed: ${error.message}`);
-        process.exit(1);
-    }
-});
 // Info command: show installed and available Photons
 program
-    .command('info')
+    .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')
     .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.workingDir || DEFAULT_WORKING_DIR;
+        const workingDir = parentOpts.dir || DEFAULT_WORKING_DIR;
         const asMcp = options.mcp || false;
         const mcps = await listPhotonMCPs(workingDir);
         // Initialize marketplace manager for all operations
@@ -547,8 +661,8 @@ program
             if (asMcp) {
                 // MCP config only works for installed photons
                 if (!isInstalled) {
-                    console.error(`❌ '${name}' is not installed`);
-                    console.error(`Install with: photon add ${name}`);
+                    printError(`'${name}' is not installed`);
+                    printInfo(`Install with: photon add ${name}`);
                     process.exit(1);
                 }
                 // Show as MCP config for single Photon
@@ -563,15 +677,20 @@ program
                 }
                 // Check for global photon installation
                 const globalPhotonPath = await getGlobalPhotonPath();
+                const needsWorkingDir = workingDir !== DEFAULT_WORKING_DIR;
                 const config = globalPhotonPath
                     ? {
                         command: globalPhotonPath,
-                        args: ['mcp', name],
+                        args: needsWorkingDir
+                            ? ['mcp', name, '--dir', workingDir]
+                            : ['mcp', name],
                         ...(Object.keys(env).length > 0 && { env }),
                     }
                     : {
                         command: 'npx',
-                        args: ['@portel/photon', 'mcp', name],
+                        args: needsWorkingDir
+                            ? ['@portel/photon', 'mcp', name, '--dir', workingDir]
+                            : ['@portel/photon', 'mcp', name],
                         ...(Object.keys(env).length > 0 && { env }),
                     };
                 // Get OS-specific config path
@@ -590,60 +709,70 @@ program
                     const fileName = `${name}.photon.ts`;
                     const metadata = await manager.getPhotonInstallMetadata(fileName);
                     const isModified = metadata ? await manager.isPhotonModified(filePath, fileName) : false;
-                    console.error(`INSTALLED IN ${workingDir}:`);
-                    console.error(`  📦 ${name}${photonMetadata.version ? ` (v${photonMetadata.version})` : ''}`);
-                    console.error(`  Location: ${filePath}`);
+                    printInfo(`Installed in ${workingDir}:\n`);
+                    // Build info as tree structure
+                    const infoData = {
+                        name: name,
+                        version: photonMetadata.version || '-',
+                        location: filePath,
+                    };
                     if (photonMetadata.description) {
-                        console.error(`  Description: ${photonMetadata.description}`);
+                        infoData.description = photonMetadata.description;
                     }
                     if (metadata) {
-                        console.error(`  Installed: ${new Date(metadata.installedAt).toLocaleDateString()}`);
+                        infoData.installed = new Date(metadata.installedAt).toLocaleDateString();
+                        infoData.source = metadata.marketplace;
                         if (isModified) {
-                            console.error(`  Status: ⚠️  Modified locally`);
+                            infoData.status = 'modified locally';
                         }
                     }
                     const toolCount = photonMetadata.tools?.length || 0;
                     if (toolCount > 0) {
-                        console.error(`  Tools: ${toolCount}`);
+                        infoData.tools = toolCount;
                     }
-                    console.error('');
+                    formatOutput(infoData, 'tree');
+                    console.log('');
                     // Show appropriate run command
                     if (metadata && !isModified) {
-                        console.error(`  Run with: photon mcp ${name}`);
-                        console.error(`  To customize: Copy to a new name and run with --dev for hot reload`);
+                        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) {
-                        console.error(`  Run with: photon mcp ${name} --dev`);
-                        console.error(`  Note: Modified from marketplace - consider renaming to avoid upgrade conflicts`);
+                        printInfo(`Run with: photon mcp ${name} --dev`);
+                        printInfo(`Note: Modified from marketplace - consider renaming to avoid upgrade conflicts`);
                     }
                     else {
-                        console.error(`  Run with: photon mcp ${name} --dev`);
+                        printInfo(`Run with: photon mcp ${name} --dev`);
                     }
-                    console.error('');
+                    console.log('');
                 }
                 // Show marketplace availability in tree format
                 const searchResults = await manager.search(name);
                 if (searchResults.size > 0) {
-                    console.error('AVAILABLE IN MARKETPLACES:');
+                    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);
-                        // Group by marketplace
+                        // Build marketplace data as tree
+                        const marketplaceData = {};
                         for (const source of sources) {
                             const isCurrentlyInstalled = installMetadata?.marketplace === source.marketplace.name;
-                            const mark = isCurrentlyInstalled ? ' ✓ currently installed' : '';
                             const version = source.metadata?.version || 'unknown';
-                            console.error(`  ${source.marketplace.name} (${source.marketplace.repo})`);
-                            console.error(`    └─ ${name} (v${version})${mark}`);
+                            marketplaceData[source.marketplace.name] = {
+                                version,
+                                source: source.marketplace.repo,
+                                status: isCurrentlyInstalled ? 'installed' : '-',
+                            };
                         }
+                        formatOutput(marketplaceData, 'tree');
                     }
                 }
                 else if (!isInstalled) {
-                    console.error(`❌ '${name}' not found locally or in any marketplace`);
-                    console.error(`Tip: Use 'photon search <query>' to find similar MCPs`);
+                    printError(`'${name}' not found locally or in any marketplace`);
+                    printInfo(`Tip: Use 'photon search <query>' to find similar MCPs`);
                     process.exit(1);
                 }
             }
@@ -655,6 +784,7 @@ program
             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)
@@ -671,12 +801,16 @@ program
                 allConfigs[mcpName] = globalPhotonPath
                     ? {
                         command: globalPhotonPath,
-                        args: ['mcp', mcpName],
+                        args: needsWorkingDir
+                            ? ['mcp', mcpName, '--dir', workingDir]
+                            : ['mcp', mcpName],
                         ...(Object.keys(env).length > 0 && { env }),
                     }
                     : {
                         command: 'npx',
-                        args: ['@portel/photon', 'mcp', mcpName],
+                        args: needsWorkingDir
+                            ? ['@portel/photon', 'mcp', mcpName, '--dir', workingDir]
+                            : ['@portel/photon', 'mcp', mcpName],
                         ...(Object.keys(env).length > 0 && { env }),
                     };
             }
@@ -688,9 +822,10 @@ program
             return;
         }
         // Normal list mode - show both installed and available
-        // Show installed photons
+        // Show installed photons as table
         if (mcps.length > 0) {
-            console.error(`INSTALLED IN ${workingDir} (${mcps.length}):`);
+            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);
@@ -699,145 +834,227 @@ program
                 if (metadata) {
                     // Has metadata - show version and status
                     const isModified = await manager.isPhotonModified(filePath, fileName);
-                    const modifiedMark = isModified ? ' ⚠️  modified' : '';
-                    console.error(`  📦 ${mcpName} (v${metadata.version} from ${metadata.marketplace})${modifiedMark}`);
+                    tableData.push({
+                        name: mcpName,
+                        version: metadata.version,
+                        source: metadata.marketplace,
+                        status: isModified ? 'modified' : STATUS.OK,
+                    });
                 }
                 else {
                     // No metadata - local or pre-metadata Photon
-                    console.error(`  📦 ${mcpName}`);
+                    tableData.push({
+                        name: mcpName,
+                        version: '-',
+                        source: 'local',
+                        status: STATUS.OK,
+                    });
                 }
             }
-            console.error('');
+            formatOutput(tableData, 'table');
+            console.log('');
         }
         else {
-            console.error(`No photons installed in ${workingDir}`);
-            console.error(`Install with: photon add <name>\n`);
+            printInfo(`No photons installed in ${workingDir}`);
+            printInfo(`Install with: photon add <name>\n`);
         }
         // Show marketplace availability in tree format
-        console.error('AVAILABLE IN MARKETPLACES:');
+        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) {
-                console.error(`  ${marketplace.name} (${marketplace.repo})`);
                 // 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);
-                    samples.forEach((photon, idx) => {
-                        const isLast = idx === samples.length - 1 && samples.length === count;
-                        const branch = isLast ? '└─' : '├─';
-                        const installedMark = mcps.includes(photon.name) ? ' ✓ installed' : '';
-                        console.error(`    ${branch} ${photon.name} (v${photon.version})${installedMark}`);
+                    const photonList = {};
+                    samples.forEach((photon) => {
+                        const installedMark = mcps.includes(photon.name) ? ' (installed)' : '';
+                        photonList[photon.name] = `v${photon.version}${installedMark}`;
                     });
                     if (count > 3) {
-                        console.error(`    └─ ... (${count - 3} more)`);
+                        photonList['...'] = `${count - 3} more`;
                     }
+                    marketplaceTree[`${marketplace.name} (${marketplace.repo})`] = photonList;
                 }
             }
             else {
-                console.error(`  ${marketplace.name} (${marketplace.repo}) - no manifest`);
+                marketplaceTree[marketplace.name] = 'no manifest';
             }
         }
-        console.error(`\nDetails: photon info <name>`);
-        console.error(`MCP config: photon info <name> --mcp`);
+        formatOutput(marketplaceTree, 'tree');
+        console.log('');
+        printInfo(`Details: photon info <name>`);
+        printInfo(`MCP config: photon info <name> --mcp`);
     }
     catch (error) {
-        console.error(`❌ Error: ${error.message}`);
+        const { printError } = await import('./cli-formatter.js');
+        printError(error.message);
         process.exit(1);
     }
 });
 // Search command: search for MCPs across marketplaces
 program
-    .command('search')
+    .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) {
-            console.error('🔄 Refreshed marketplace data...\n');
+            printInfo('Refreshed marketplace data...\n');
         }
-        console.error(`Searching for '${query}' in marketplaces...`);
+        printInfo(`Searching for '${query}' in marketplaces...`);
         const results = await manager.search(query);
         if (results.size === 0) {
-            console.error(`❌ No results found for '${query}'`);
-            console.error(`Tip: Run 'photon marketplace update' to manually refresh marketplace data`);
+            printError(`No results found for '${query}'`);
+            printInfo(`Tip: Run 'photon marketplace update' to manually refresh marketplace data`);
             return;
         }
-        console.error('');
+        // Build table data from search results
+        const tableData = [];
         for (const [mcpName, entries] of results) {
             for (const entry of entries) {
-                if (entry.metadata) {
-                    console.error(`  📦 ${mcpName} (v${entry.metadata.version})`);
-                    console.error(`     ${entry.metadata.description}`);
-                    console.error(`     ${entry.marketplace.name} (${entry.marketplace.repo})`);
-                    if (entry.metadata.tags && entry.metadata.tags.length > 0) {
-                        console.error(`     Tags: ${entry.metadata.tags.join(', ')}`);
-                    }
-                }
-                else {
-                    console.error(`  📦 ${mcpName}`);
-                    console.error(`     ✓ ${entry.marketplace.name} (${entry.marketplace.repo})`);
-                }
+                tableData.push({
+                    name: mcpName,
+                    version: entry.metadata?.version || '-',
+                    description: entry.metadata?.description
+                        ? entry.metadata.description.substring(0, 50) + (entry.metadata.description.length > 50 ? '...' : '')
+                        : '-',
+                    marketplace: entry.marketplace.name,
+                });
             }
         }
-        console.error('');
+        console.log('');
+        formatOutput(tableData, 'table');
+        printInfo(`\nInstall with: photon add <name>`);
     }
     catch (error) {
-        console.error(`❌ Error: ${error.message}`);
+        const { printError } = await import('./cli-formatter.js');
+        printError(error.message);
         process.exit(1);
     }
 });
-// Sync command: synchronize local resources
-const sync = program
-    .command('sync')
-    .description('Synchronize local resources');
-sync
-    .command('marketplace')
-    .argument('[path]', 'Directory containing Photons (defaults to current directory)', '.')
-    .option('--name <name>', 'Marketplace name')
-    .option('--description <desc>', 'Marketplace description')
-    .option('--owner <owner>', 'Owner name')
-    .option('--claude-code', 'Generate Claude Code plugin files')
-    .description('Generate/sync marketplace manifest and documentation')
-    .action(async (dirPath, options) => {
+// Maker command: commands for photon creators/publishers
+const maker = program
+    .command('maker', { hidden: true })
+    .description('Commands for creating photons and marketplaces');
+// maker new: create a new photon from template
+maker
+    .command('new')
+    .argument('<name>', 'Name for the new photon')
+    .description('Create a new photon from template')
+    .action(async (name, options, command) => {
     try {
-        await performMarketplaceSync(dirPath, options);
-        // Generate Claude Code plugin if requested
-        if (options.claudeCode) {
-            const { generateClaudeCodePlugin } = await import('./claude-code-plugin.js');
-            await generateClaudeCodePlugin(dirPath, options);
+        // Get working directory from global options
+        const workingDir = program.opts().dir || DEFAULT_WORKING_DIR;
+        // Ensure working directory exists
+        await ensureWorkingDir(workingDir);
+        const fileName = `${name}.photon.ts`;
+        const filePath = path.join(workingDir, fileName);
+        // Check if file already exists
+        try {
+            await fs.access(filePath);
+            console.error(`❌ File already exists: ${filePath}`);
+            process.exit(1);
+        }
+        catch {
+            // File doesn't exist, good
+        }
+        // Read template
+        const templatePath = path.join(__dirname, '..', 'templates', 'photon.template.ts');
+        let template;
+        try {
+            template = await fs.readFile(templatePath, 'utf-8');
         }
+        catch {
+            // Fallback inline template if file not found
+            template = getInlineTemplate();
+        }
+        // Replace placeholders
+        // Convert kebab-case to PascalCase for class name
+        const className = name
+            .split(/[-_]/)
+            .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+            .join('');
+        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}`);
-        if (process.env.DEBUG) {
-            console.error(error.stack);
+        process.exit(1);
+    }
+});
+// maker validate: validate photon syntax and schemas
+maker
+    .command('validate')
+    .argument('<name>', 'Photon name (without .photon.ts extension)')
+    .description('Validate photon syntax and schemas')
+    .action(async (name, options, command) => {
+    try {
+        // 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);
+        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);
         }
+        console.error(`Validating ${path.basename(filePath)}...\n`);
+        // Import loader and try to load
+        const { PhotonLoader } = await import('./loader.js');
+        const loader = new PhotonLoader(false); // quiet mode for inspection
+        const mcp = await loader.loadFile(filePath);
+        console.error(`✅ Valid Photon`);
+        console.error(`Name: ${mcp.name}`);
+        console.error(`Tools: ${mcp.tools.length}`);
+        for (const tool of mcp.tools) {
+            console.error(`  - ${tool.name}: ${tool.description}`);
+        }
+        process.exit(0);
+    }
+    catch (error) {
+        console.error(`❌ Validation failed: ${error.message}`);
         process.exit(1);
     }
 });
-// Marketplace command: manage MCP marketplaces
-const marketplace = program
-    .command('marketplace')
-    .description('Manage MCP marketplaces');
-marketplace
-    .command('sync', { hidden: true })
-    .argument('[path]', 'Directory containing Photons (defaults to current directory)', '.')
+// maker sync: generate marketplace manifest
+maker
+    .command('sync')
+    .option('--dir <path>', 'Directory to sync (defaults to current directory)')
     .option('--name <name>', 'Marketplace name')
     .option('--description <desc>', 'Marketplace description')
     .option('--owner <owner>', 'Owner name')
-    .description('(Deprecated: use "photon sync marketplace") Generate/sync marketplace manifest and documentation')
-    .action(async (dirPath, options) => {
-    console.error('⚠️  Note: "photon marketplace sync" is deprecated. Use "photon sync marketplace" instead.\n');
+    .option('--claude-code', 'Generate Claude Code plugin files')
+    .description('Generate marketplace manifest and documentation from your photons')
+    .action(async (options) => {
     try {
-        await performMarketplaceSync(dirPath, options);
+        const dirPath = options.dir || '.';
+        const resolvedPath = path.resolve(dirPath);
+        // Only filter installed photons when syncing ~/.photon
+        const filterInstalled = resolvedPath === DEFAULT_WORKING_DIR;
+        await performMarketplaceSync(dirPath, { ...options, filterInstalled });
+        // Generate Claude Code plugin if requested
+        if (options.claudeCode) {
+            const { generateClaudeCodePlugin } = await import('./claude-code-plugin.js');
+            await generateClaudeCodePlugin(dirPath, options);
+        }
     }
     catch (error) {
         console.error(`❌ Error: ${error.message}`);
@@ -847,107 +1064,17 @@ marketplace
         process.exit(1);
     }
 });
-// Initialize a new marketplace with git hooks
-marketplace
+maker
     .command('init')
-    .argument('[path]', 'Directory to initialize as marketplace (defaults to current directory)', '.')
+    .option('--dir <path>', 'Directory to initialize (defaults to current directory)')
     .option('--name <name>', 'Marketplace name')
     .option('--description <desc>', 'Marketplace description')
     .option('--owner <owner>', 'Owner name')
     .description('Initialize a directory as a Photon marketplace with git hooks')
-    .action(async (dirPath, options) => {
+    .action(async (options) => {
     try {
-        const fs = await import('fs/promises');
-        const { existsSync } = await import('fs');
-        const path = await import('path');
-        const absolutePath = path.resolve(dirPath);
-        // Check if directory exists
-        if (!existsSync(absolutePath)) {
-            await fs.mkdir(absolutePath, { recursive: true });
-            console.error(`📁 Created directory: ${absolutePath}`);
-        }
-        // 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);
-        }
-        // Create .githooks directory
-        const hooksDir = path.join(absolutePath, '.githooks');
-        await fs.mkdir(hooksDir, { recursive: true });
-        // Create pre-commit hook
-        const preCommitHook = `#!/bin/bash
-# Pre-commit hook: Auto-sync marketplace manifest before commit
-# This ensures .marketplace/photons.json and .claude-plugin/ are always up-to-date
-
-# Check if any .photon.ts files or marketplace files are being committed
-if git diff --cached --name-only | grep -qE '\\.photon\\.ts$|\\.marketplace/|\\.claude-plugin/'; then
-  echo "🔄 Syncing marketplace manifest..."
-
-  # Run photon sync marketplace with --claude-code to generate plugin files
-  if photon sync marketplace --claude-code; then
-    # Stage the generated files
-    git add .marketplace/photons.json README.md *.md .claude-plugin/ 2>/dev/null
-    echo "✅ Marketplace and Claude Code plugin synced and staged"
-  else
-    echo "❌ Failed to sync marketplace"
-    exit 1
-  fi
-fi
-
-exit 0
-`;
-        const preCommitPath = path.join(hooksDir, 'pre-commit');
-        await fs.writeFile(preCommitPath, preCommitHook, { mode: 0o755 });
-        console.error('✅ Created .githooks/pre-commit');
-        // Create setup script
-        const setupScript = `#!/bin/bash
-# Setup script to install git hooks for this marketplace
-
-REPO_ROOT="$(git rev-parse --show-toplevel)"
-HOOKS_DIR="$REPO_ROOT/.git/hooks"
-SOURCE_HOOKS="$REPO_ROOT/.githooks"
-
-echo "🔧 Installing git hooks for Photon marketplace..."
-
-# Copy pre-commit hook
-if [ -f "$SOURCE_HOOKS/pre-commit" ]; then
-  cp "$SOURCE_HOOKS/pre-commit" "$HOOKS_DIR/pre-commit"
-  chmod +x "$HOOKS_DIR/pre-commit"
-  echo "✅ Installed pre-commit hook (auto-syncs marketplace manifest)"
-else
-  echo "❌ pre-commit hook not found"
-  exit 1
-fi
-
-echo ""
-echo "✅ Git hooks installed successfully!"
-echo ""
-echo "The pre-commit hook will automatically run 'photon sync marketplace'"
-echo "whenever you commit changes to .photon.ts files."
-`;
-        const setupPath = path.join(hooksDir, 'setup.sh');
-        await fs.writeFile(setupPath, setupScript, { mode: 0o755 });
-        console.error('✅ Created .githooks/setup.sh');
-        // Install hooks to .git/hooks
-        const gitHooksDir = path.join(absolutePath, '.git', 'hooks');
-        const gitPreCommitPath = path.join(gitHooksDir, 'pre-commit');
-        await fs.writeFile(gitPreCommitPath, preCommitHook, { mode: 0o755 });
-        console.error('✅ Installed hooks to .git/hooks');
-        // Create .marketplace directory
-        const marketplaceDir = path.join(absolutePath, '.marketplace');
-        await fs.mkdir(marketplaceDir, { recursive: true });
-        console.error('✅ Created .marketplace directory');
-        // Run initial sync
-        console.error('\n🔄 Running initial marketplace sync...\n');
-        await performMarketplaceSync(dirPath, options);
-        console.error('\n✅ Marketplace initialized successfully!');
-        console.error('\nNext steps:');
-        console.error('1. Add your .photon.ts files to this directory');
-        console.error('2. Commit your changes (hooks will auto-sync)');
-        console.error('3. Push to GitHub to share your marketplace');
-        console.error('\nContributors can setup hooks with:');
-        console.error('  bash .githooks/setup.sh');
+        const dirPath = options.dir || '.';
+        await performMarketplaceInit(dirPath, options);
     }
     catch (error) {
         console.error(`❌ Error: ${error.message}`);
@@ -957,38 +1084,40 @@ echo "whenever you commit changes to .photon.ts files."
         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) {
-            console.error('No marketplaces configured');
+            printInfo('No marketplaces configured');
+            printInfo('Add one with: photon marketplace add portel-dev/photons');
             return;
         }
         // Get MCP counts
         const counts = await manager.getMarketplaceCounts();
-        console.error(`Configured marketplaces (${marketplaces.length}):\n`);
-        for (const marketplace of marketplaces) {
-            const status = marketplace.enabled ? '✅' : '❌';
-            const count = counts.get(marketplace.name) || 0;
-            const countStr = count > 0 ? `${count} available` : 'no manifest';
-            console.error(`  ${status} ${marketplace.name}`);
-            console.error(`     ${marketplace.repo}`);
-            console.error(`     ${countStr}`);
-            if (marketplace.lastUpdated) {
-                const date = new Date(marketplace.lastUpdated);
-                console.error(`     Updated ${date.toLocaleDateString()}`);
-            }
-        }
-        console.error('');
+        // 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) {
-        console.error(`❌ Error: ${error.message}`);
+        const { printError } = await import('./cli-formatter.js');
+        printError(error.message);
         process.exit(1);
     }
 });
@@ -1093,51 +1222,9 @@ marketplace
         process.exit(1);
     }
 });
-marketplace
-    .command('update')
-    .argument('[name]', 'Marketplace name to update (updates all if omitted)')
-    .description('Update marketplace metadata from remote')
-    .action(async (name) => {
-    try {
-        const { MarketplaceManager } = await import('./marketplace-manager.js');
-        const manager = new MarketplaceManager();
-        await manager.initialize();
-        if (name) {
-            // Update specific marketplace
-            console.error(`Updating ${name}...`);
-            const success = await manager.updateMarketplaceCache(name);
-            if (success) {
-                console.error(`✅ Updated ${name}`);
-            }
-            else {
-                console.error(`❌ Failed to update ${name} (not found or no manifest)`);
-                process.exit(1);
-            }
-        }
-        else {
-            // Update all enabled marketplaces
-            console.error(`Updating all marketplaces...\n`);
-            const results = await manager.updateAllCaches();
-            for (const [marketplaceName, success] of results) {
-                if (success) {
-                    console.error(`  ✅ ${marketplaceName}`);
-                }
-                else {
-                    console.error(`  ⚠️  ${marketplaceName} (no manifest)`);
-                }
-            }
-            const successCount = Array.from(results.values()).filter(Boolean).length;
-            console.error(`\nUpdated ${successCount}/${results.size} marketplaces`);
-        }
-    }
-    catch (error) {
-        console.error(`❌ Error: ${error.message}`);
-        process.exit(1);
-    }
-});
 // Add command: add MCP from marketplace
 program
-    .command('add')
+    .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')
@@ -1145,7 +1232,7 @@ program
     .action(async (name, options, command) => {
     try {
         // Get working directory from global options
-        const workingDir = command.parent?.opts().workingDir || DEFAULT_WORKING_DIR;
+        const workingDir = command.parent?.opts().dir || DEFAULT_WORKING_DIR;
         await ensureWorkingDir(workingDir);
         const { MarketplaceManager } = await import('./marketplace-manager.js');
         const manager = new MarketplaceManager();
@@ -1320,16 +1407,68 @@ program
         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) => {
+    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`);
+            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')
+    .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().workingDir || DEFAULT_WORKING_DIR;
+        const workingDir = command.parent?.opts().dir || DEFAULT_WORKING_DIR;
         const { VersionChecker } = await import('./version-checker.js');
         const checker = new VersionChecker();
         await checker.initialize();
@@ -1337,230 +1476,568 @@ program
             // Upgrade single MCP
             const filePath = await resolvePhotonPath(name, workingDir);
             if (!filePath) {
-                console.error(`❌ MCP not found: ${name}`);
-                console.error(`Searched in: ${workingDir}`);
+                printError(`MCP not found: ${name}`);
+                printInfo(`Searched in: ${workingDir}`);
                 process.exit(1);
             }
-            console.error(`Checking ${name} for updates...`);
+            printInfo(`Checking ${name} for updates...`);
             const versionInfo = await checker.checkForUpdate(name, filePath);
             if (!versionInfo.local) {
-                console.error(`⚠️  Could not determine local version`);
+                printWarning('Could not determine local version');
                 return;
             }
             if (!versionInfo.remote) {
-                console.error(`⚠️  Not found in any marketplace. This might be a local-only MCP.`);
+                printWarning('Not found in any marketplace. This might be a local-only MCP.');
                 return;
             }
             if (options.check) {
-                if (versionInfo.needsUpdate) {
-                    console.error(`🔄 Update available: ${versionInfo.local} → ${versionInfo.remote}`);
-                }
-                else {
-                    console.error(`✅ Already up to date (${versionInfo.local})`);
-                }
+                const tableData = [{
+                        name,
+                        local: versionInfo.local,
+                        remote: versionInfo.remote,
+                        status: versionInfo.needsUpdate ? STATUS.UPDATE : STATUS.OK,
+                    }];
+                formatOutput(tableData, 'table');
                 return;
             }
             if (!versionInfo.needsUpdate) {
-                console.error(`✅ Already up to date (${versionInfo.local})`);
+                printSuccess(`Already up to date (${versionInfo.local})`);
                 return;
             }
-            console.error(`🔄 Upgrading ${name}: ${versionInfo.local} → ${versionInfo.remote}`);
+            printInfo(`Upgrading ${name}: ${versionInfo.local} → ${versionInfo.remote}`);
             const success = await checker.updateMCP(name, filePath);
             if (success) {
-                console.error(`✅ Successfully upgraded ${name} to ${versionInfo.remote}`);
+                printSuccess(`Successfully upgraded ${name} to ${versionInfo.remote}`);
             }
             else {
-                console.error(`❌ Failed to upgrade ${name}`);
+                printError(`Failed to upgrade ${name}`);
                 process.exit(1);
             }
         }
         else {
             // Check/upgrade all MCPs
-            console.error(`Checking all MCPs in ${workingDir}...\n`);
+            printInfo(`Checking all MCPs in ${workingDir}...\n`);
             const updates = await checker.checkAllUpdates(workingDir);
             if (updates.size === 0) {
-                console.error(`No MCPs found`);
+                printInfo('No MCPs found');
                 return;
             }
             const needsUpdate = [];
+            // Build table data
+            const tableData = [];
             for (const [mcpName, info] of updates) {
-                const status = checker.formatVersionInfo(info);
                 if (info.needsUpdate) {
-                    console.error(`  🔄 ${mcpName}: ${status}`);
                     needsUpdate.push(mcpName);
+                    tableData.push({
+                        name: mcpName,
+                        local: info.local || '-',
+                        remote: info.remote || '-',
+                        status: STATUS.UPDATE,
+                    });
                 }
                 else if (info.local && info.remote) {
-                    console.error(`  ✅ ${mcpName}: ${status}`);
+                    tableData.push({
+                        name: mcpName,
+                        local: info.local,
+                        remote: info.remote,
+                        status: STATUS.OK,
+                    });
                 }
                 else {
-                    console.error(`  📦 ${mcpName}: ${status}`);
+                    tableData.push({
+                        name: mcpName,
+                        local: info.local || '-',
+                        remote: info.remote || 'local only',
+                        status: STATUS.UNKNOWN,
+                    });
                 }
             }
+            formatOutput(tableData, 'table');
             if (needsUpdate.length === 0) {
-                console.error(`\nAll MCPs are up to date!`);
+                console.log('');
+                printSuccess('All MCPs are up to date!');
                 return;
             }
             if (options.check) {
-                console.error(`\n${needsUpdate.length} MCP(s) have updates available`);
-                console.error(`Run 'photon upgrade' to upgrade all`);
+                console.log('');
+                printInfo(`${needsUpdate.length} MCP(s) have updates available`);
+                printInfo(`Run 'photon upgrade' to upgrade all`);
                 return;
             }
             // Upgrade all that need updates
-            console.error(`\nUpgrading ${needsUpdate.length} MCP(s)...`);
+            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) {
-                    console.error(`✅ Upgraded ${mcpName}`);
+                    printSuccess(`Upgraded ${mcpName}`);
                 }
                 else {
-                    console.error(`❌ Failed to upgrade ${mcpName}`);
+                    printError(`Failed to upgrade ${mcpName}`);
                 }
             }
         }
     }
     catch (error) {
-        console.error(`❌ Error: ${error.message}`);
+        const { printError } = await import('./cli-formatter.js');
+        printError(error.message);
         process.exit(1);
     }
 });
-// Audit command: security scan for MCP dependencies
+// Clear-cache command: clear compiled photon cache
 program
-    .command('audit')
-    .argument('[name]', 'MCP name to audit (audits all if omitted)')
-    .description('Security audit of MCP dependencies')
+    .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 workingDir = command.parent?.opts().workingDir || DEFAULT_WORKING_DIR;
-        const { DependencyManager } = await import('./dependency-manager.js');
-        const { SecurityScanner } = await import('./security-scanner.js');
-        const depManager = new DependencyManager();
-        const scanner = new SecurityScanner();
+        const { printInfo, printSuccess, printError } = await import('./cli-formatter.js');
+        const cacheDir = path.join(os.homedir(), '.cache', 'photon-mcp', 'compiled');
         if (name) {
-            // Audit single MCP
+            // Clear cache for specific photon
+            const workingDir = command.parent?.opts().dir || DEFAULT_WORKING_DIR;
             const filePath = await resolvePhotonPath(name, workingDir);
             if (!filePath) {
-                console.error(`❌ MCP not found: ${name}`);
+                printError(`Photon not found: ${name}`);
+                printInfo(`Tip: Use 'photon info' to see installed photons`);
                 process.exit(1);
             }
-            console.error(`🔍 Auditing dependencies for: ${name}\n`);
-            const dependencies = await depManager.extractDependencies(filePath);
-            if (dependencies.length === 0) {
-                console.error('✅ No dependencies to audit');
-                return;
-            }
-            const depStrings = dependencies.map(d => `${d.name}@${d.version}`);
-            const result = await scanner.auditMCP(name, depStrings);
-            console.error(scanner.formatAuditResult(result));
-            if (result.totalVulnerabilities > 0) {
-                console.error('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-                console.error('Vulnerabilities found:');
-                result.dependencies.forEach(dep => {
-                    if (dep.hasVulnerabilities) {
-                        console.error(`\n📦 ${dep.dependency}@${dep.version}`);
-                        dep.vulnerabilities.forEach(vuln => {
-                            const symbol = scanner.getSeveritySymbol(vuln.severity);
-                            console.error(`   ${symbol} ${vuln.severity.toUpperCase()}: ${vuln.title}`);
-                            if (vuln.url) {
-                                console.error(`      ${vuln.url}`);
-                            }
-                        });
-                    }
-                });
-                console.error('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-                console.error('\n💡 To fix vulnerabilities:');
-                console.error(`   1. Update dependency versions in @dependencies JSDoc tag`);
-                console.error(`   2. Clear cache: photon clear-cache`);
-                console.error(`   3. Restart MCP to reinstall with new versions`);
-                if (result.criticalCount > 0 || result.highCount > 0) {
-                    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 {
-            // Audit all MCPs
-            console.error('🔍 Auditing all MCPs...\n');
-            const mcps = await listPhotonMCPs(workingDir);
-            if (mcps.length === 0) {
-                console.error('No MCPs found');
-                return;
-            }
-            let totalVulnerabilities = 0;
-            let mcpsWithVulnerabilities = 0;
-            for (const mcp of mcps) {
-                const mcpPath = path.join(workingDir, mcp);
-                const mcpName = path.basename(mcp, '.photon.ts');
-                const dependencies = await depManager.extractDependencies(mcpPath);
-                if (dependencies.length === 0) {
-                    console.error(`✅ ${mcpName}: No dependencies`);
-                    continue;
+            // Clear all cache
+            printInfo('Clearing all compiled photon cache...');
+            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
+                    }
                 }
-                const depStrings = dependencies.map(d => `${d.name}@${d.version}`);
-                const result = await scanner.auditMCP(mcpName, depStrings);
-                console.error(scanner.formatAuditResult(result));
-                if (result.totalVulnerabilities > 0) {
-                    totalVulnerabilities += result.totalVulnerabilities;
-                    mcpsWithVulnerabilities++;
+                if (count > 0) {
+                    printSuccess(`Cleared ${count} cached file(s)`);
+                }
+                else {
+                    printInfo(`Cache is already empty`);
                 }
             }
-            console.error('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-            console.error(`\nSummary: ${totalVulnerabilities} vulnerabilities in ${mcpsWithVulnerabilities}/${mcps.length} MCPs`);
-            if (totalVulnerabilities > 0) {
-                console.error('\nRun: photon audit <name>  # for detailed vulnerability info');
-                process.exit(1);
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    printInfo(`No cache directory found`);
+                }
+                else {
+                    throw error;
+                }
             }
         }
     }
     catch (error) {
-        console.error(`❌ Error: ${error.message}`);
+        const { printError } = await import('./cli-formatter.js');
+        printError(error.message);
         process.exit(1);
     }
 });
-// Conflicts command: show MCPs available in multiple marketplaces
+// Doctor command: diagnose photon environment
 program
-    .command('conflicts')
-    .description('Show MCPs available in multiple marketplaces')
-    .action(async () => {
+    .command('doctor', { hidden: true })
+    .argument('[name]', 'Photon name to diagnose (checks environment if omitted)')
+    .description('Run diagnostics on photon environment and installations')
+    .action(async (name, options, command) => {
     try {
-        const { MarketplaceManager } = await import('./marketplace-manager.js');
-        const manager = new MarketplaceManager();
-        await manager.initialize();
-        console.error('🔍 Scanning for MCP conflicts across marketplaces...\n');
-        const conflicts = await manager.detectAllConflicts();
-        if (conflicts.size === 0) {
-            console.error('✅ No conflicts detected');
-            console.error('\nAll MCPs are uniquely available from single marketplaces.');
-            return;
+        const { formatOutput, 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 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)
+            issuesFound++;
+        // Check npm/npx
+        try {
+            const { execSync } = await import('child_process');
+            const npmVersion = execSync('npm --version', { encoding: 'utf-8' }).trim();
+            diagnostics['Package Manager'] = {
+                npm: npmVersion,
+                status: STATUS.OK,
+            };
         }
-        console.error(`⚠️  Found ${conflicts.size} MCP(s) in multiple marketplaces:\n`);
-        for (const [mcpName, sources] of conflicts) {
-            console.error(`📦 ${mcpName}`);
-            sources.forEach(source => {
-                const version = source.metadata?.version || 'unknown';
-                const description = source.metadata?.description || '';
-                console.error(`   → ${source.marketplace.name} (v${version})`);
-                if (description) {
-                    console.error(`     ${description.substring(0, 60)}${description.length > 60 ? '...' : ''}`);
+        catch {
+            diagnostics['Package Manager'] = {
+                npm: 'not found',
+                status: STATUS.ERROR,
+            };
+            issuesFound++;
+        }
+        // Check working directory
+        try {
+            await fs.access(workingDir);
+            const stats = await fs.stat(workingDir);
+            if (stats.isDirectory()) {
+                const mcps = await listPhotonMCPs(workingDir);
+                diagnostics['Working Directory'] = {
+                    path: workingDir,
+                    status: STATUS.OK,
+                    photons: mcps.length,
+                };
+            }
+            else {
+                diagnostics['Working Directory'] = {
+                    path: workingDir,
+                    status: STATUS.ERROR,
+                    note: 'not a directory',
+                };
+                issuesFound++;
+            }
+        }
+        catch {
+            diagnostics['Working Directory'] = {
+                path: workingDir,
+                status: STATUS.UNKNOWN,
+                note: 'will be created on first use',
+            };
+        }
+        // Check cache directory
+        const cacheDir = path.join(os.homedir(), '.cache', 'photon-mcp', 'compiled');
+        try {
+            await fs.access(cacheDir);
+            const files = await fs.readdir(cacheDir);
+            diagnostics['Cache Directory'] = {
+                path: cacheDir,
+                status: STATUS.OK,
+                cachedFiles: files.length,
+            };
+        }
+        catch {
+            diagnostics['Cache Directory'] = {
+                path: cacheDir,
+                status: STATUS.UNKNOWN,
+                note: 'will be created on first use',
+            };
+        }
+        // Check marketplaces and conflicts
+        let manager;
+        try {
+            const { MarketplaceManager } = await import('./marketplace-manager.js');
+            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),
+                    };
+                }
+            }
+            else {
+                diagnostics['Marketplaces'] = {
+                    enabled: 0,
+                    status: STATUS.UNKNOWN,
+                    note: 'Add one with: photon marketplace add portel-dev/photons',
+                };
+            }
+        }
+        catch (error) {
+            diagnostics['Marketplaces'] = {
+                status: STATUS.ERROR,
+                error: error.message,
+            };
+            issuesFound++;
+        }
+        // Check specific photon if provided
+        if (name) {
+            const photonDiag = {};
+            const filePath = await resolvePhotonPath(name, workingDir);
+            if (!filePath) {
+                photonDiag['location'] = 'not found';
+                photonDiag['status'] = STATUS.ERROR;
+                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++;
+                }
+                // Check cache
+                const cachedFile = path.join(cacheDir, `${name}.js`);
+                try {
+                    await fs.access(cachedFile);
+                    photonDiag['cache'] = STATUS.OK;
+                }
+                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}`;
                 }
-            });
-            // Show recommendation
-            const conflict = await manager.checkConflict(mcpName);
-            if (conflict.recommendation) {
-                console.error(`   💡 Recommended: ${conflict.recommendation}`);
             }
-            console.error('');
+            diagnostics[`Photon: ${name}`] = photonDiag;
+        }
+        formatOutput(diagnostics, 'tree');
+        // Summary
+        console.log('');
+        if (issuesFound === 0) {
+            printSuccess('No issues found! Photon environment is healthy.');
+        }
+        else {
+            printWarning(`Found ${issuesFound} issue(s). Please address the items marked with '${STATUS.ERROR}' above.`);
+            process.exit(1);
         }
-        console.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-        console.error('\n💡 Tip: Use --marketplace flag to specify which to use:');
-        console.error('   photon add <name> --marketplace <marketplace-name>');
-        console.error('\nOr disable marketplaces you don\'t need:');
-        console.error('   photon marketplace disable <marketplace-name>');
     }
     catch (error) {
-        console.error(`❌ Error: ${error.message}`);
+        const { printError } = await import('./cli-formatter.js');
+        printError(error.message);
         process.exit(1);
     }
 });
+// CLI command: directly invoke photon methods
+program
+    .command('cli <photon> [method] [args...]', { hidden: true })
+    .description('Run photon methods directly from the command line')
+    .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...]
+
+DESCRIPTION:
+    Run photon methods directly from the command line. Photons provide
+    a CLI interface automatically based on their exported methods.
+
+EXAMPLES:
+    # List all methods for a photon
+    photon cli lg-remote
+
+    # Call a method with no parameters
+    photon cli 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
+
+    # Get method-specific help
+    photon cli lg-remote volume --help
+
+    # Output raw JSON instead of formatted text
+    photon cli lg-remote status --json
+
+SEE ALSO:
+    photon info           List all installed photons
+    photon add <name>     Install a photon from marketplace
+    photon alias          Create CLI shortcuts for photons
+`);
+        return;
+    }
+    const { listMethods, runMethod } = await import('./photon-cli-runner.js');
+    if (!method) {
+        // List all methods
+        await listMethods(photon);
+    }
+    else {
+        // Run specific method
+        await runMethod(photon, method, args);
+    }
+});
+// Alias commands: create CLI shortcuts for photons
+program
+    .command('alias', { hidden: true })
+    .argument('<photon>', 'Photon to create alias for')
+    .argument('[alias-name]', 'Custom alias name (defaults to photon name)')
+    .description('Create a CLI alias for a photon')
+    .action(async (photon, aliasName) => {
+    const { createAlias } = await import('./cli-alias.js');
+    await createAlias(photon, aliasName);
+});
+program
+    .command('unalias', { hidden: true })
+    .argument('<alias-name>', 'Alias to remove')
+    .description('Remove a CLI alias')
+    .action(async (aliasName) => {
+    const { removeAlias } = await import('./cli-alias.js');
+    await removeAlias(aliasName);
+});
+program
+    .command('aliases', { hidden: true })
+    .description('List all CLI aliases')
+    .action(async () => {
+    const { listAliases } = await import('./cli-alias.js');
+    await listAliases();
+});
+// 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',
+];
+const knownSubcommands = {
+    marketplace: ['list', 'add', 'remove', 'enable', 'disable'],
+    maker: ['new', 'validate', 'sync', 'init'],
+};
+/**
+ * Calculate Levenshtein distance between two strings
+ */
+function levenshteinDistance(a, b) {
+    const matrix = [];
+    for (let i = 0; i <= b.length; i++) {
+        matrix[i] = [i];
+    }
+    for (let j = 0; j <= a.length; j++) {
+        matrix[0][j] = j;
+    }
+    for (let i = 1; i <= b.length; i++) {
+        for (let j = 1; j <= a.length; j++) {
+            if (b.charAt(i - 1) === a.charAt(j - 1)) {
+                matrix[i][j] = matrix[i - 1][j - 1];
+            }
+            else {
+                matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, // substitution
+                matrix[i][j - 1] + 1, // insertion
+                matrix[i - 1][j] + 1 // deletion
+                );
+            }
+        }
+    }
+    return matrix[b.length][a.length];
+}
+/**
+ * Find closest matching command
+ */
+function findClosestCommand(input, commands) {
+    let closest = null;
+    let minDistance = Infinity;
+    for (const cmd of commands) {
+        const distance = levenshteinDistance(input.toLowerCase(), cmd.toLowerCase());
+        // Only suggest if distance is small enough (max 3 edits for short commands, proportional for longer)
+        const maxDistance = Math.max(2, Math.floor(cmd.length / 2));
+        if (distance < minDistance && distance <= maxDistance) {
+            minDistance = distance;
+            closest = cmd;
+        }
+    }
+    return closest;
+}
+// Handle unknown commands with "did you mean" suggestions
+program.on('command:*', async (operands) => {
+    const { printError, printInfo } = await import('./cli-formatter.js');
+    const unknownCommand = operands[0];
+    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]);
+    if (parentIndex !== -1 && parentIndex < args.indexOf(unknownCommand)) {
+        const parent = args[parentIndex];
+        const suggestion = findClosestCommand(unknownCommand, knownSubcommands[parent]);
+        if (suggestion) {
+            printInfo(`Did you mean: photon ${parent} ${suggestion}`);
+        }
+    }
+    else {
+        // Check for top-level command typo
+        const suggestion = findClosestCommand(unknownCommand, knownCommands);
+        if (suggestion) {
+            printInfo(`Did you mean: photon ${suggestion}`);
+        }
+    }
+    console.log('');
+    printInfo(`Run 'photon --help' for usage`);
+    process.exit(1);
+});
 program.parse();
 /**
  * Inline template fallback