@portel/photon 1.4.0 → 1.5.1

package/dist/photon-doc-extractor.js

@@ -1,5 +1,7 @@
 import * as fs from 'fs/promises';
+import * as path from 'path';
 import { SchemaExtractor } from '@portel/photon-core';
+import { PHOTON_VERSION } from './version.js';
 /**
  * Extracts comprehensive documentation from Photon files
  *
@@ -22,20 +24,34 @@ export class PhotonDocExtractor {
         this.content = await fs.readFile(this.filePath, 'utf-8');
         const statefulTag = this.extractTag('stateful');
         const idleTimeoutTag = this.extractTag('idleTimeout');
+        const internalTag = this.extractTag('internal');
+        const tools = await this.extractTools();
+        const photonType = this.detectPhotonType(tools);
+        const features = this.detectFeatures(tools, statefulTag !== undefined);
+        const externalDeps = this.extractDependencies();
+        const diagram = this.generateDiagramSync(tools, photonType, externalDeps);
         return {
             name: this.extractName(),
-            version: this.extractTag('version') || '1.0.0',
+            version: this.extractTag('version') || PHOTON_VERSION,
             description: this.extractDescription(),
             author: this.extractTag('author'),
             license: this.extractTag('license'),
             repository: this.extractTag('repository'),
             homepage: this.extractTag('homepage'),
+            icon: this.extractTag('icon'),
+            internal: internalTag !== undefined,
             configParams: this.extractConfigParams(),
             setupInstructions: this.extractSetupInstructions(),
-            tools: await this.extractTools(),
+            tools,
             dependencies: this.extractTag('dependencies'),
-            stateful: statefulTag === 'true',
+            runtime: this.extractTag('runtime'),
+            stateful: statefulTag !== undefined,
             idleTimeout: idleTimeoutTag ? parseInt(idleTimeoutTag, 10) : undefined,
+            assets: await this.extractAssets(),
+            photonType,
+            features,
+            externalDeps,
+            diagram,
         };
     }
     /**
@@ -62,9 +78,18 @@ export class PhotonDocExtractor {
      * Extract a specific JSDoc tag value
      */
     extractTag(tagName) {
-        const regex = new RegExp(`@${tagName}\\s+(.+?)(?=\\n|$)`, 'm');
-        const match = this.content.match(regex);
-        return match ? match[1].trim() : undefined;
+        // First try to match tag with value: @tagName value
+        const regexWithValue = new RegExp(`@${tagName}\\s+(.+?)(?=\\n|$)`, 'm');
+        const matchWithValue = this.content.match(regexWithValue);
+        if (matchWithValue) {
+            return matchWithValue[1].trim();
+        }
+        // Then check for boolean tag without value: @tagName (followed by newline, *, or end)
+        const regexBoolean = new RegExp(`@${tagName}(?:\\s*\\n|\\s*\\*|$)`, 'm');
+        if (this.content.match(regexBoolean)) {
+            return 'true'; // Presence of tag means true
+        }
+        return undefined;
     }
     /**
      * Extract configuration parameters from constructor
@@ -80,7 +105,10 @@ export class PhotonDocExtractor {
         return params.map((param) => {
             // Convert to environment variable format
             // ClassName -> class-name -> CLASS_NAME_PARAM_NAME
-            const kebabCase = className.replace(/([A-Z])/g, '-$1').toLowerCase().replace(/^-/, '');
+            const kebabCase = className
+                .replace(/([A-Z])/g, '-$1')
+                .toLowerCase()
+                .replace(/^-/, '');
             const envPrefix = kebabCase.toUpperCase().replace(/-/g, '_');
             const envVar = `${envPrefix}_${param.name.toUpperCase()}`;
             // Find description from Configuration section
@@ -138,21 +166,74 @@ export class PhotonDocExtractor {
         // Clean up the configuration text
         return configMatch[1]
             .split('\n')
-            .map(line => line.replace(/^\s*\*\s?/, '').trim())
-            .filter(line => line.length > 0)
+            .map((line) => line.replace(/^\s*\*\s?/, '').trim())
+            .filter((line) => line.length > 0)
             .join('\n')
             .trim();
     }
+    /**
+     * Extract assets associated with the Photon
+     * Scans for ui/, prompts/, resources/ folders and @ui annotations
+     */
+    async extractAssets() {
+        const assets = new Set();
+        const dir = path.dirname(this.filePath);
+        const basename = path.basename(this.filePath, '.photon.ts');
+        // Convention: asset folder has same name as photon (without .photon.ts)
+        // e.g. test-ui.photon.ts -> test-ui/
+        const assetFolder = path.join(dir, basename);
+        // Check if asset folder exists
+        try {
+            const stats = await fs.stat(assetFolder);
+            if (stats.isDirectory()) {
+                // Recursively find all files in the asset folder
+                const findFiles = async (currentDir, relativePath) => {
+                    const entries = await fs.readdir(currentDir, { withFileTypes: true });
+                    for (const entry of entries) {
+                        const entryPath = path.join(currentDir, entry.name);
+                        const entryRelative = path.join(relativePath, entry.name);
+                        if (entry.isDirectory()) {
+                            await findFiles(entryPath, entryRelative);
+                        }
+                        else {
+                            // Add relative path from photon file's directory
+                            // e.g. test-ui/ui/index.html
+                            assets.add(path.join(basename, entryRelative));
+                        }
+                    }
+                };
+                await findFiles(assetFolder, '');
+            }
+        }
+        catch {
+            // Asset folder doesn't exist, ignore
+        }
+        // Extract explicit @ui assets from JSDoc
+        // Format: @ui <id> <path>
+        const uiRegex = /@ui[ \t]+\S+[ \t]+(\S+)/g;
+        let match;
+        while ((match = uiRegex.exec(this.content)) !== null) {
+            const assetPath = match[1];
+            // Only include relative paths
+            if (assetPath.startsWith('./') || !path.isAbsolute(assetPath)) {
+                // Normalize path
+                const normalized = assetPath.startsWith('./') ? assetPath.slice(2) : assetPath;
+                assets.add(normalized);
+            }
+        }
+        return Array.from(assets);
+    }
     /**
      * Extract tool methods with their documentation
      */
     async extractTools() {
         const tools = [];
-        // First, find all async methods
-        const methodRegex = /async\s+(\w+)\s*\([^)]*\)/g;
+        // Find all async methods (including generators with async *)
+        const methodRegex = /async\s+(\*?)\s*(\w+)\s*\([^)]*\)/g;
         let match;
         while ((match = methodRegex.exec(this.content)) !== null) {
-            const methodName = match[1];
+            const isGenerator = match[1] === '*';
+            const methodName = match[2];
             const methodIndex = match.index;
             // Skip private methods (starting with _) and lifecycle methods
             if (methodName.startsWith('_') ||
@@ -177,6 +258,7 @@ export class PhotonDocExtractor {
             const jsdoc = jsdocMatch[1];
             const tool = this.parseToolMethodFromJSDoc(jsdoc, methodName);
             if (tool) {
+                tool.isGenerator = isGenerator;
                 tools.push(tool);
             }
         }
@@ -215,24 +297,50 @@ export class PhotonDocExtractor {
             constraints.push(`pattern: ${patternMatch[1]}`);
             cleanDesc = cleanDesc.replace(/\{@pattern\s+[^}]+\}\s*/g, '');
         }
-        // Extract {@example value} - handle nested braces in JSON examples
+        // Extract {@choice value1,value2,...}
+        const choiceMatch = cleanDesc.match(/\{@choice\s+([^}]+)\}/);
+        if (choiceMatch) {
+            constraints.push(`choice: ${choiceMatch[1]}`);
+            cleanDesc = cleanDesc.replace(/\{@choice\s+[^}]+\}\s*/g, '');
+        }
+        // Extract {@field type}
+        const fieldMatch = cleanDesc.match(/\{@field\s+([a-z]+)\}/);
+        if (fieldMatch) {
+            constraints.push(`field: ${fieldMatch[1]}`);
+            cleanDesc = cleanDesc.replace(/\{@field\s+[a-z]+\}\s*/g, '');
+        }
+        // Extract {@example value} - handle nested braces and brackets in JSON examples
         const exampleStart = cleanDesc.indexOf('{@example ');
         if (exampleStart !== -1) {
             const contentStart = exampleStart + '{@example '.length;
-            let depth = 0;
+            let braceDepth = 0;
+            let bracketDepth = 0;
             let i = contentStart;
-            // Find the closing } by counting braces
+            let inString = false;
+            // Find the closing } by counting braces and brackets, respecting strings
             while (i < cleanDesc.length) {
-                if (cleanDesc[i] === '{')
-                    depth++;
-                else if (cleanDesc[i] === '}') {
-                    if (depth === 0) {
-                        // Found the closing brace of the {@example} tag
-                        example = cleanDesc.substring(contentStart, i).trim();
-                        cleanDesc = cleanDesc.substring(0, exampleStart) + cleanDesc.substring(i + 1);
-                        break;
+                const ch = cleanDesc[i];
+                const prevCh = i > 0 ? cleanDesc[i - 1] : '';
+                // Handle string boundaries (skip escaped quotes)
+                if (ch === '"' && prevCh !== '\\') {
+                    inString = !inString;
+                }
+                else if (!inString) {
+                    if (ch === '{')
+                        braceDepth++;
+                    else if (ch === '[')
+                        bracketDepth++;
+                    else if (ch === ']')
+                        bracketDepth--;
+                    else if (ch === '}') {
+                        if (braceDepth === 0 && bracketDepth === 0) {
+                            // Found the closing brace of the {@example} tag
+                            example = cleanDesc.substring(contentStart, i).trim();
+                            cleanDesc = cleanDesc.substring(0, exampleStart) + cleanDesc.substring(i + 1);
+                            break;
+                        }
+                        braceDepth--;
                     }
-                    depth--;
                 }
                 i++;
             }
@@ -254,7 +362,7 @@ export class PhotonDocExtractor {
         const description = descMatch
             ? descMatch[1]
                 .split('\n')
-                .map(line => line.replace(/^\s*\*\s?/, '').trim())
+                .map((line) => line.replace(/^\s*\*\s?/, '').trim())
                 .join(' ')
                 .trim()
             : '';
@@ -271,7 +379,10 @@ export class PhotonDocExtractor {
             // Format: "Param description (optional)" or "Param description (default: value)"
             let cleanDesc = parsed.description;
             const optional = /\(optional\)/i.test(cleanDesc) || /\(default:/i.test(cleanDesc);
-            cleanDesc = cleanDesc.replace(/\(optional\)/gi, '').replace(/\(default:.*?\)/gi, '').trim();
+            cleanDesc = cleanDesc
+                .replace(/\(optional\)/gi, '')
+                .replace(/\(default:.*?\)/gi, '')
+                .trim();
             params.push({
                 name: paramName,
                 type: 'any', // Type extraction from JSDoc would need more parsing
@@ -288,7 +399,7 @@ export class PhotonDocExtractor {
         if (exampleMatch) {
             const exampleText = exampleMatch[1]
                 .split('\n')
-                .map(line => line.replace(/^\s*\*\s?/, ''))
+                .map((line) => line.replace(/^\s*\*\s?/, ''))
                 .join('\n')
                 .trim();
             // Only use it if it looks like actual code (not just a simple value from inline tag)
@@ -304,5 +415,403 @@ export class PhotonDocExtractor {
             example,
         };
     }
+    // ============================================
+    // FEATURE DETECTION
+    // ============================================
+    /**
+     * Detect platform features used by this Photon
+     */
+    detectFeatures(tools, isStateful) {
+        const features = [];
+        // generator — any async * method
+        if (tools.some((t) => t.isGenerator)) {
+            features.push('generator');
+        }
+        // custom-ui — @ui JSDoc tag
+        if (this.extractTag('ui') !== undefined || /@ui\s+\S+/.test(this.content)) {
+            features.push('custom-ui');
+        }
+        // elicitation — yield { ask: patterns
+        if (/yield\s*\{\s*ask\s*:/.test(this.content) || /yield\*\s/.test(this.content)) {
+            features.push('elicitation');
+        }
+        // streaming — yield { emit: or yield { step:
+        if (/yield\s*\{\s*(emit|step)\s*:/.test(this.content)) {
+            features.push('streaming');
+        }
+        // oauth — yield { ask: 'oauth'
+        if (/yield\s*\{\s*ask\s*:\s*['"]oauth['"]/.test(this.content)) {
+            features.push('oauth');
+        }
+        // stateful — @stateful tag
+        if (isStateful) {
+            features.push('stateful');
+        }
+        // webhooks — webhook endpoint patterns
+        if (/webhook/i.test(this.content) && /@webhook/.test(this.content)) {
+            features.push('webhooks');
+        }
+        // channels — channel in emit patterns
+        if (/channel/i.test(this.content) && /emit/.test(this.content)) {
+            features.push('channels');
+        }
+        // locks — acquireLock / releaseLock
+        if (/acquireLock|releaseLock/.test(this.content)) {
+            features.push('locks');
+        }
+        // mcp-bridge — this.mcp( calls
+        if (/this\.mcp\(/.test(this.content)) {
+            features.push('mcp-bridge');
+        }
+        // photon-bridge — this.photon( calls
+        if (/this\.photon\(/.test(this.content)) {
+            features.push('photon-bridge');
+        }
+        // wizard — @wizard tag
+        if (this.extractTag('wizard') !== undefined) {
+            features.push('wizard');
+        }
+        // dashboard — @ui + main method with linkedUi pattern
+        if (features.includes('custom-ui') &&
+            /async\s+\*?\s*main\b/.test(this.content) &&
+            /linkedUi|dashboard/i.test(this.content)) {
+            features.push('dashboard');
+        }
+        return features;
+    }
+    // ============================================
+    // DIAGRAM GENERATION
+    // ============================================
+    /**
+     * Generate a Mermaid diagram for this Photon
+     * Automatically detects the Photon type and generates appropriate diagram
+     */
+    async generateDiagram() {
+        if (!this.content) {
+            this.content = await fs.readFile(this.filePath, 'utf-8');
+        }
+        const tools = await this.extractTools();
+        const photonType = this.detectPhotonType(tools);
+        const name = this.extractName();
+        const deps = this.extractDependencies();
+        switch (photonType) {
+            case 'workflow':
+                return this.generateWorkflowDiagram(name, tools, deps);
+            case 'streaming':
+                return this.generateStreamingDiagram(name, tools, deps);
+            default:
+                return this.generateApiSurfaceDiagram(name, tools, deps);
+        }
+    }
+    /**
+     * Generate diagram synchronously when content and tools are already loaded
+     */
+    generateDiagramSync(tools, photonType, deps) {
+        const name = this.extractName();
+        switch (photonType) {
+            case 'workflow':
+                return this.generateWorkflowDiagram(name, tools, deps);
+            case 'streaming':
+                return this.generateStreamingDiagram(name, tools, deps);
+            default:
+                return this.generateApiSurfaceDiagram(name, tools, deps);
+        }
+    }
+    /**
+     * Detect the type of Photon based on its methods
+     */
+    detectPhotonType(tools) {
+        const hasGenerator = tools.some((t) => t.isGenerator);
+        const hasAskEmit = this.hasAskEmitPatterns();
+        if (hasGenerator && hasAskEmit)
+            return 'workflow';
+        if (hasGenerator)
+            return 'streaming';
+        return 'api';
+    }
+    /**
+     * Check if content has ask/emit yield patterns
+     */
+    hasAskEmitPatterns() {
+        return /yield\s*\{\s*(ask|emit)\s*:/.test(this.content);
+    }
+    /**
+     * Extract dependencies from JSDoc tags
+     */
+    extractDependencies() {
+        const mcpsTag = this.extractTag('mcps');
+        const photonsTag = this.extractTag('photons');
+        const depsTag = this.extractTag('dependencies');
+        return {
+            mcps: mcpsTag ? mcpsTag.split(/[,\s]+/).filter(Boolean) : [],
+            photons: photonsTag ? photonsTag.split(/[,\s]+/).filter(Boolean) : [],
+            npm: depsTag
+                ? depsTag
+                    .split(/[,\s]+/)
+                    .map((d) => d.split('@')[0])
+                    .filter(Boolean)
+                : [],
+        };
+    }
+    /**
+     * Extract yield statements from content
+     */
+    extractYieldStatements() {
+        const yields = [];
+        // Match: const varName = yield { ask: 'type', message: '...' }
+        // or: yield { emit: 'type', message: '...' }
+        const yieldRegex = /(?:const\s+(\w+)\s*(?::\s*\w+)?\s*=\s*)?yield\s*\{\s*(ask|emit)\s*:\s*['"](\w+)['"]\s*(?:,\s*message\s*:\s*[`'"]([^`'"]*)[`'"])?/g;
+        let match;
+        while ((match = yieldRegex.exec(this.content)) !== null) {
+            yields.push({
+                variable: match[1],
+                type: match[2],
+                subtype: match[3],
+                message: match[4],
+            });
+        }
+        return yields;
+    }
+    /**
+     * Extract MCP and Photon calls from content
+     */
+    extractExternalCalls() {
+        const calls = [];
+        // Match: this.mcp('name').method() or await this.mcp('name').method()
+        const mcpRegex = /this\.mcp\(['"](\w+)['"]\)\.(\w+)/g;
+        let match;
+        while ((match = mcpRegex.exec(this.content)) !== null) {
+            calls.push({ type: 'mcp', name: match[1], method: match[2] });
+        }
+        // Match: this.photon('name').method() or yield* this.photon('name').method()
+        const photonRegex = /this\.photon\(['"](\w+)['"]\)\.(\w+)/g;
+        while ((match = photonRegex.exec(this.content)) !== null) {
+            calls.push({ type: 'photon', name: match[1], method: match[2] });
+        }
+        return calls;
+    }
+    /**
+     * Infer emoji based on method/tool name
+     */
+    inferEmoji(name) {
+        const lower = name.toLowerCase();
+        if (/^(read|get|fetch|load|find|query|search|list)/.test(lower))
+            return '📖';
+        if (/^(write|create|save|put|add|insert|set)/.test(lower))
+            return '✏️';
+        if (/^(delete|remove|drop|clear)/.test(lower))
+            return '🗑️';
+        if (/^(send|post|push|publish|notify)/.test(lower))
+            return '📤';
+        if (/^(update|modify|patch|edit)/.test(lower))
+            return '🔄';
+        if (/^(validate|check|verify|test)/.test(lower))
+            return '✅';
+        if (/^(config|setup|init)/.test(lower))
+            return '⚙️';
+        if (/^(run|execute|start|begin)/.test(lower))
+            return '▶️';
+        if (/^(stop|cancel|abort|end)/.test(lower))
+            return '⏹️';
+        if (/^(connect|login|auth)/.test(lower))
+            return '🔌';
+        if (/^(download|export)/.test(lower))
+            return '📥';
+        if (/^(upload|import)/.test(lower))
+            return '📤';
+        return '🔧';
+    }
+    /**
+     * Get emoji for ask type
+     */
+    getAskEmoji(subtype) {
+        switch (subtype) {
+            case 'confirm':
+                return '🙋';
+            case 'select':
+                return '📋';
+            case 'text':
+                return '✏️';
+            case 'number':
+                return '🔢';
+            case 'password':
+                return '🔒';
+            case 'date':
+                return '📅';
+            case 'file':
+                return '📁';
+            default:
+                return '❓';
+        }
+    }
+    /**
+     * Get emoji for emit type
+     */
+    getEmitEmoji(subtype) {
+        switch (subtype) {
+            case 'status':
+                return '📢';
+            case 'progress':
+                return '⏳';
+            case 'log':
+                return '📝';
+            case 'toast':
+                return '🎉';
+            case 'thinking':
+                return '🧠';
+            case 'artifact':
+                return '📊';
+            case 'stream':
+                return '💬';
+            default:
+                return '📣';
+        }
+    }
+    /**
+     * Generate API surface diagram for tool collection Photons
+     */
+    generateApiSurfaceDiagram(name, tools, deps) {
+        const lines = ['flowchart LR'];
+        // Main photon subgraph
+        lines.push(`    subgraph ${this.sanitizeId(name)}["📦 ${this.titleCase(name)}"]`);
+        lines.push('        direction TB');
+        lines.push('        PHOTON((🎯))');
+        tools.forEach((tool, i) => {
+            const emoji = this.inferEmoji(tool.name);
+            const id = `T${i}`;
+            lines.push(`        ${id}[${emoji} ${tool.name}]`);
+            lines.push(`        PHOTON --> ${id}`);
+        });
+        lines.push('    end');
+        // Dependencies subgraph (if any)
+        const hasDeps = deps.mcps.length > 0 || deps.photons.length > 0 || deps.npm.length > 0;
+        if (hasDeps) {
+            lines.push('');
+            lines.push('    subgraph deps["Dependencies"]');
+            lines.push('        direction TB');
+            deps.mcps.forEach((mcp, i) => {
+                lines.push(`        MCP${i}[🔌 ${mcp}]`);
+            });
+            deps.photons.forEach((photon, i) => {
+                lines.push(`        PHO${i}[📦 ${photon}]`);
+            });
+            deps.npm.forEach((pkg, i) => {
+                lines.push(`        NPM${i}[📚 ${pkg}]`);
+            });
+            lines.push('    end');
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Generate streaming diagram for generator Photons without ask/emit
+     */
+    generateStreamingDiagram(name, tools, deps) {
+        // For streaming, show tools with streaming indicator
+        const lines = ['flowchart LR'];
+        lines.push(`    subgraph ${this.sanitizeId(name)}["📦 ${this.titleCase(name)}"]`);
+        lines.push('        direction TB');
+        lines.push('        PHOTON((🎯))');
+        tools.forEach((tool, i) => {
+            const emoji = tool.isGenerator ? '🌊' : this.inferEmoji(tool.name);
+            const id = `T${i}`;
+            const suffix = tool.isGenerator ? ' (stream)' : '';
+            lines.push(`        ${id}[${emoji} ${tool.name}${suffix}]`);
+            lines.push(`        PHOTON --> ${id}`);
+        });
+        lines.push('    end');
+        return lines.join('\n');
+    }
+    /**
+     * Generate workflow flowchart for Photons with ask/emit patterns
+     */
+    generateWorkflowDiagram(name, tools, deps) {
+        const yields = this.extractYieldStatements();
+        const externalCalls = this.extractExternalCalls();
+        const lines = ['flowchart TD'];
+        lines.push(`    subgraph ${this.sanitizeId(name)}["📦 ${this.titleCase(name)}"]`);
+        lines.push('        START([▶ Start])');
+        let prevNode = 'START';
+        let nodeCounter = 0;
+        // Process yields and calls in order they appear
+        for (const y of yields) {
+            const nodeId = `N${nodeCounter++}`;
+            if (y.type === 'emit') {
+                const emoji = this.getEmitEmoji(y.subtype);
+                const msg = y.message ? this.truncate(y.message, 30) : y.subtype;
+                lines.push(`        ${nodeId}[${emoji} ${msg}]`);
+                lines.push(`        ${prevNode} --> ${nodeId}`);
+                prevNode = nodeId;
+            }
+            else if (y.type === 'ask') {
+                const emoji = this.getAskEmoji(y.subtype);
+                const msg = y.message ? this.truncate(y.message, 25) : y.subtype;
+                lines.push(`        ${nodeId}{${emoji} ${msg}}`);
+                lines.push(`        ${prevNode} --> ${nodeId}`);
+                // For confirm, add Yes/No branches
+                if (y.subtype === 'confirm') {
+                    const cancelId = `N${nodeCounter++}`;
+                    const continueId = `N${nodeCounter++}`;
+                    lines.push(`        ${cancelId}([❌ Cancelled])`);
+                    lines.push(`        ${nodeId} -->|No| ${cancelId}`);
+                    lines.push(`        ${nodeId} -->|Yes| ${continueId}`);
+                    // Create a dummy continue node for the flow
+                    lines.push(`        ${continueId}[Continue]`);
+                    prevNode = continueId;
+                }
+                else {
+                    prevNode = nodeId;
+                }
+            }
+        }
+        // Add external calls
+        for (const call of externalCalls) {
+            const nodeId = `N${nodeCounter++}`;
+            const emoji = call.type === 'mcp' ? '🔌' : '📦';
+            lines.push(`        ${nodeId}[${emoji} ${call.name}.${call.method}]`);
+            lines.push(`        ${prevNode} --> ${nodeId}`);
+            prevNode = nodeId;
+        }
+        // End node
+        lines.push(`        SUCCESS([✅ Success])`);
+        lines.push(`        ${prevNode} --> SUCCESS`);
+        lines.push('    end');
+        // Dependencies
+        const hasDeps = deps.mcps.length > 0 || deps.photons.length > 0;
+        if (hasDeps) {
+            lines.push('');
+            lines.push('    subgraph deps["Dependencies"]');
+            deps.mcps.forEach((mcp, i) => {
+                lines.push(`        DEP_MCP${i}[🔌 ${mcp}]`);
+            });
+            deps.photons.forEach((photon, i) => {
+                lines.push(`        DEP_PHO${i}[📦 ${photon}]`);
+            });
+            lines.push('    end');
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Sanitize string for use as Mermaid node ID
+     */
+    sanitizeId(str) {
+        return str.replace(/[^a-zA-Z0-9_]/g, '_');
+    }
+    /**
+     * Convert kebab-case to Title Case
+     */
+    titleCase(str) {
+        return str
+            .split('-')
+            .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+            .join(' ');
+    }
+    /**
+     * Truncate string to max length
+     */
+    truncate(str, maxLen) {
+        if (str.length <= maxLen)
+            return str;
+        return str.slice(0, maxLen - 3) + '...';
+    }
 }
 //# sourceMappingURL=photon-doc-extractor.js.map