portfolio_element_manager
Manage individual portfolio elements between local storage and GitHub repository. Download or upload personas, skills, and other elements using fuzzy matching for easy identification.
Instructions
Manage individual elements between your local portfolio and GitHub repository. USE THIS TO DOWNLOAD/UPLOAD INDIVIDUAL PERSONAS, SKILLS, OR OTHER ELEMENTS! When a user asks to 'download X persona from my GitHub' or 'upload Y skill to GitHub', use this tool. Operations: 'download' (GitHub→local), 'upload' (local→GitHub), 'list-remote' (see what's on GitHub), 'compare' (diff local vs GitHub). FUZZY MATCHING enabled - 'verbose victorian scholar' will find 'Verbose-Victorian-Scholar'. After downloading, use reload_elements then activate_element.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | The operation to perform. 'download' = get from GitHub to local, 'upload' = send from local to GitHub, 'list-remote' = see what's on GitHub, 'compare' = see differences | |
| element_name | No | Name of the element (required for download, upload, compare). FUZZY MATCHING ENABLED: Just type the name naturally - 'verbose victorian scholar', 'Victorian Scholar', 'verbose-victorian', etc. will all work | |
| element_type | No | Type of element (required for download, upload, compare). For personas use 'personas' | |
| filter | No | Filters for bulk operations | |
| options | No | Additional options. For downloads, use options:{force:true} to skip confirmations |
Implementation Reference
- src/server/tools/ConfigToolsV2.ts:49-111 (registration)Tool registration and schema definition for 'portfolio_element_manager'. Delegates execution to server.handleSyncOperation.
tool: { name: "portfolio_element_manager", description: "Manage individual elements between your local portfolio and GitHub repository. USE THIS TO DOWNLOAD/UPLOAD INDIVIDUAL PERSONAS, SKILLS, OR OTHER ELEMENTS! When a user asks to 'download X persona from my GitHub' or 'upload Y skill to GitHub', use this tool. Operations: 'download' (GitHub→local), 'upload' (local→GitHub), 'list-remote' (see what's on GitHub), 'compare' (diff local vs GitHub). FUZZY MATCHING enabled - 'verbose victorian scholar' will find 'Verbose-Victorian-Scholar'. After downloading, use reload_elements then activate_element.", inputSchema: { type: "object", properties: { operation: { type: "string", enum: ["list-remote", "download", "upload", "compare"], description: "The operation to perform. 'download' = get from GitHub to local, 'upload' = send from local to GitHub, 'list-remote' = see what's on GitHub, 'compare' = see differences" }, element_name: { type: "string", description: "Name of the element (required for download, upload, compare). FUZZY MATCHING ENABLED: Just type the name naturally - 'verbose victorian scholar', 'Victorian Scholar', 'verbose-victorian', etc. will all work" }, element_type: { type: "string", enum: ["personas", "skills", "templates", "agents", "memories", "ensembles"], description: "Type of element (required for download, upload, compare). For personas use 'personas'" }, filter: { type: "object", properties: { type: { type: "string", enum: ["personas", "skills", "templates", "agents", "memories", "ensembles"], description: "Filter by element type" }, author: { type: "string", description: "Filter by author username" }, updated_after: { type: "string", description: "Filter by update date (ISO 8601 format)" } }, description: "Filters for bulk operations" }, options: { type: "object", properties: { force: { type: "boolean", description: "Force overwrite existing elements. Use force:true when downloading to skip confirmation prompts" }, dry_run: { type: "boolean", description: "Preview changes without applying them" }, include_private: { type: "boolean", description: "Include elements marked as private/local-only" } }, description: "Additional options. For downloads, use options:{force:true} to skip confirmations" } }, required: ["operation"] } }, handler: (args: any) => server.handleSyncOperation(args) } - src/handlers/SyncHandlerV2.ts:41-87 (handler)Direct handler implementation (server.handleSyncOperation). Processes args, calls PortfolioSyncManager, formats results.
async handleSyncOperation(options: SyncOperationOptions, indicator: string = '') { try { await this.configManager.initialize(); // Check if sync is enabled (allow list-remote and compare even when disabled) const syncEnabled = this.configManager.getSetting('sync.enabled'); const readOnlyOperations = ['list-remote', 'compare']; if (!syncEnabled && !readOnlyOperations.includes(options.operation)) { return { content: [{ type: "text", text: `${indicator}⚠️ **Sync is Disabled**\n\n` + `Portfolio sync is currently disabled for privacy.\n\n` + `To enable sync:\n` + `\`dollhouse_config action: "set", setting: "sync.enabled", value: true\`\n\n` + `You can still use \`list-remote\` and \`compare\` to view differences.` }] }; } // Map our operation to PortfolioSyncManager's SyncOperation format const syncOp: SyncOperation = { operation: this.mapOperation(options.operation), element_name: options.element_name, element_type: options.element_type || options.filter?.type, // Use filter.type if element_type not provided bulk: options.operation.includes('bulk'), show_diff: options.operation === 'compare', force: options.options?.force, confirm: options.options?.force || options.options?.dry_run === false // force implies confirm, dry_run=false means confirm }; // Call the unified handleSyncOperation method const result = await this.syncManager.handleSyncOperation(syncOp); // Format the result based on the operation type return this.formatResult(result, options, indicator); } catch (error) { const sanitizedError = SecureErrorHandler.sanitizeError(error); return { content: [{ type: "text", text: `${indicator}❌ Sync operation failed: ${sanitizedError.message}` }] }; } } - Core handler dispatching to specific operations (download, upload, list-remote, compare) with full business logic.
public async handleSyncOperation(params: SyncOperation): Promise<SyncResult> { try { // Check if sync is enabled in config const config = this.configManager.getConfig(); if (!config.sync.enabled && params.operation !== 'list-remote') { return { success: false, message: 'Sync is disabled. Enable it with: dollhouse_config --action update --setting sync.enabled --value true' }; } // Check bulk permissions if (params.bulk) { const bulkAllowed = this.isBulkOperationAllowed(params.operation, config); if (!bulkAllowed.allowed) { return { success: false, message: bulkAllowed.message }; } } // Handle operations switch (params.operation) { case 'list-remote': return await this.listRemoteElements(params.element_type); case 'download': if (params.bulk) { return await this.bulkDownload(params.element_type, params.confirm); } else if (params.element_name) { return await this.downloadElement( params.element_name, params.element_type!, params.version, params.force ); } else { return { success: false, message: 'Element name required for individual download' }; } case 'upload': if (params.bulk) { return await this.bulkUpload(params.element_type, params.confirm); } else if (params.element_name) { return await this.uploadElement( params.element_name, params.element_type!, params.confirm ); } else { return { success: false, message: 'Element name required for individual upload' }; } case 'compare': if (params.element_name && params.element_type) { return await this.compareVersions( params.element_name, params.element_type, params.show_diff ); } else { return { success: false, message: 'Element name and type required for comparison' }; } default: return { success: false, message: `Unknown operation: ${params.operation}` }; } } catch (error) { logger.error('Sync operation failed', { operation: params.operation, error: error instanceof Error ? error.message : String(error) }); return { success: false, message: `Sync operation failed: ${error instanceof Error ? error.message : String(error)}` }; } } - Key helper method for downloading individual elements from GitHub with fuzzy matching and conflict resolution.
private async downloadElement( elementName: string, elementType: ElementType, version?: string, force?: boolean ): Promise<SyncResult> { try { const config = this.configManager.getConfig(); // Validate element name const validation = UnicodeValidator.normalize(elementName); if (!validation.isValid) { return { success: false, message: `Invalid element name: ${validation.detectedIssues?.[0] || 'unknown error'}` }; } // Get token and set it const token = await TokenManager.getGitHubTokenAsync(); if (!token) { return { success: false, message: 'GitHub authentication required' }; } this.repoManager.setToken(token); // Get GitHub index const index = await this.indexer.getIndex(); // Find the element - first try exact match, then fuzzy match const entries = index.elements.get(elementType) || []; let entry = entries.find(e => e.name === elementName); // If exact match not found, try fuzzy matching if (!entry) { // Try case-insensitive exact match first entry = entries.find(e => e.name.toLowerCase() === elementName.toLowerCase()); // If still not found, try fuzzy matching if (!entry) { const fuzzyMatch = this.findFuzzyMatch(elementName, entries); if (fuzzyMatch) { logger.info(`Fuzzy match found: '${elementName}' matched to '${fuzzyMatch.name}'`); entry = fuzzyMatch; } } } if (!entry) { // Generate helpful suggestions const suggestions = this.getSuggestions(elementName, entries); const suggestionText = suggestions.length > 0 ? `\n\nDid you mean one of these?\n${suggestions.map(s => ` • ${s.name}`).join('\n')}` : ''; return { success: false, message: `Element '${elementName}' (${elementType}) not found in GitHub portfolio${suggestionText}` }; } // Check for local conflicts const localPath = this.portfolioManager.getElementPath(elementType, `${elementName}.md`); let hasLocalVersion = false; let localContent: string | null = null; try { localContent = await fs.readFile(localPath, 'utf-8'); hasLocalVersion = true; } catch { // No local version exists } // Download the element const response = await fetch(entry.downloadUrl, { headers: { 'Authorization': `Bearer ${token}`, 'Accept': 'application/vnd.github.v3.raw' } }); if (!response.ok) { throw new Error(`Failed to download: ${response.statusText}`); } const remoteContent = await response.text(); // Validate content security const validationResult = ContentValidator.validateAndSanitize(remoteContent); if (!validationResult.isValid && validationResult.severity === 'critical') { return { success: false, message: `Security issue detected in remote content: ${validationResult.detectedPatterns?.join(', ')}` }; } // Check if content is different if (hasLocalVersion && localContent) { const localHash = createHash('sha256').update(localContent).digest('hex'); const remoteHash = createHash('sha256').update(remoteContent).digest('hex'); if (localHash === remoteHash) { return { success: true, message: `Element '${elementName}' is already up to date` }; } // Show confirmation for overwrite unless force flag is set if (config.sync.individual.require_confirmation && !force) { const diff = await this.generateDiff(localContent, remoteContent); return { success: false, message: `Local version exists. Please confirm download will overwrite:\n\n${diff}\n\nTo proceed, use --force flag`, data: { requiresConfirmation: true } }; } } // Save the element await fs.mkdir(path.dirname(localPath), { recursive: true }); await fs.writeFile(localPath, remoteContent, 'utf-8'); logger.info('Element downloaded from GitHub', { element: elementName, type: elementType, version: entry.version }); return { success: true, message: `Successfully downloaded '${elementName}' (${elementType}) from GitHub portfolio` }; } catch (error) { return { success: false, message: `Failed to download element: ${error instanceof Error ? error.message : String(error)}` }; } } - Key helper method for uploading individual elements to GitHub with security checks.
private async uploadElement( elementName: string, elementType: ElementType, confirm?: boolean ): Promise<SyncResult> { try { const config = this.configManager.getConfig(); // Check for local element const localPath = this.portfolioManager.getElementPath(elementType, `${elementName}.md`); let content: string; try { content = await fs.readFile(localPath, 'utf-8'); } catch { return { success: false, message: `Element '${elementName}' (${elementType}) not found locally` }; } // Check privacy metadata const parsed = SecureYamlParser.parse(content, { maxYamlSize: 64 * 1024, validateContent: false, validateFields: false }); if (parsed.data?.privacy?.local_only === true) { return { success: false, message: `Element '${elementName}' is marked as local-only and cannot be uploaded` }; } // Validate content security const validationResult = ContentValidator.validateAndSanitize(content); if (!validationResult.isValid && validationResult.severity === 'critical') { return { success: false, message: `Security issue detected: ${validationResult.detectedPatterns?.join(', ')}` }; } // Scan for sensitive content if configured if (config.sync.privacy.scan_for_secrets) { logger.debug('Scanning for secrets before upload'); // Implement actual secret scanning const secretPatterns = [ /api[_-]?key\s*[:=]\s*['"][^'"]+['"]/gi, /secret\s*[:=]\s*['"][^'"]+['"]/gi, /password\s*[:=]\s*['"][^'"]+['"]/gi, /token\s*[:=]\s*['"][^'"]+['"]/gi, /private[_-]?key\s*[:=]\s*['"][^'"]+['"]/gi ]; for (const pattern of secretPatterns) { if (pattern.test(content)) { return { success: false, message: `Potential secret detected in content. Please review and remove sensitive information before uploading.` }; } } } // Get confirmation if required (unless already confirmed) if (config.sync.individual.require_confirmation && !confirm) { return { success: false, message: `Please confirm upload of '${elementName}' (${elementType}) to GitHub.\n\nContent preview:\n${content.substring(0, 500)}...\n\nTo proceed, use --confirm flag`, data: { requiresConfirmation: true } }; } // Get token and validate const token = await TokenManager.getGitHubTokenAsync(); if (!token) { return { success: false, message: 'GitHub authentication required' }; } // Create a PortfolioElement for the adapter (fixes Issue #913) // Using PortfolioElementAdapter instead of incomplete IElement implementation const portfolioElement = { type: elementType, metadata: { name: elementName, description: parsed.data?.description || '', author: parsed.data?.author || 'unknown', created: parsed.data?.created || new Date().toISOString(), updated: new Date().toISOString(), version: parsed.data?.version || '1.0.0', tags: parsed.data?.tags || [] }, content: content }; // Use PortfolioElementAdapter to properly implement IElement interface const adapter = new PortfolioElementAdapter(portfolioElement); // Use PortfolioRepoManager to upload this.repoManager.setToken(token); // DEBUG: Log upload attempt logger.debug('[BULK_SYNC_DEBUG] Upload element attempt', { elementName, elementType, hasToken: !!token, tokenPrefix: token ? token.substring(0, 10) + '...' : 'none', adapterHasMetadata: !!(adapter && adapter.metadata), timestamp: new Date().toISOString() }); try { const url = await this.repoManager.saveElement(adapter, true); // consent is true since we've already checked logger.info('Element uploaded to GitHub', { element: elementName, type: elementType, url }); return { success: true, message: `Successfully uploaded '${elementName}' (${elementType}) to GitHub portfolio`, data: { url } }; } catch (uploadError) { // Handle specific errors if (uploadError instanceof Error && uploadError.message.includes('repository does not exist')) { return { success: false, message: `GitHub portfolio repository not found. Please initialize it first using init_portfolio tool.` }; } throw uploadError; } } catch (error) { return { success: false, message: `Failed to upload element: ${error instanceof Error ? error.message : String(error)}` }; } }