@portel/photon 1.9.0 → 1.10.0

package/dist/marketplace-manager.js

@@ -9,9 +9,10 @@ import * as crypto from 'crypto';
 import { createLogger } from './shared/logger.js';
 import { getErrorMessage } from './shared/error-handler.js';
 import { verifyContentHash, validateAssetPath, isPathWithin } from './shared/security.js';
+import { getDefaultContext } from './context.js';
 // Timeout for marketplace fetch requests
 const FETCH_TIMEOUT_MS = 10 * 1000;
-const CONFIG_DIR = path.join(os.homedir(), '.photon');
+const CONFIG_DIR = getDefaultContext().baseDir;
 const CONFIG_FILE = path.join(CONFIG_DIR, 'marketplaces.json');
 const CACHE_DIR = path.join(CONFIG_DIR, '.cache', 'marketplaces');
 const METADATA_FILE = path.join(CONFIG_DIR, '.metadata.json');
@@ -49,6 +50,28 @@ export function calculateHash(content) {
     const hash = crypto.createHash('sha256').update(content).digest('hex');
     return `sha256:${hash}`;
 }
+/**
+ * Calculate combined hash of a photon source file + its declared assets.
+ * This ensures asset-only changes (e.g. board.html update) are detected.
+ */
+export async function calculatePhotonHash(sourceFilePath, assets, baseDir) {
+    const hasher = crypto.createHash('sha256');
+    // Always include the source file
+    hasher.update(await fs.readFile(sourceFilePath, 'utf-8'));
+    // Include each asset file in sorted order for determinism
+    if (assets && assets.length > 0 && baseDir) {
+        for (const asset of [...assets].sort()) {
+            const assetPath = path.join(baseDir, asset);
+            try {
+                hasher.update(await fs.readFile(assetPath));
+            }
+            catch {
+                // Asset missing — skip (will be caught by validation)
+            }
+        }
+    }
+    return `sha256:${hasher.digest('hex')}`;
+}
 /**
  * Read local installation metadata
  */
@@ -65,24 +88,26 @@ export async function readLocalMetadata() {
     }
     return { photons: {} };
 }
-/**
- * Write local installation metadata
- */
-export async function writeLocalMetadata(metadata) {
-    await fs.mkdir(CONFIG_DIR, { recursive: true });
-    await fs.writeFile(METADATA_FILE, JSON.stringify(metadata, null, 2), 'utf-8');
-}
 export class MarketplaceManager {
     config = { marketplaces: [] };
     logger;
-    constructor(logger) {
+    configDir;
+    configFile;
+    cacheDir;
+    metadataFile;
+    constructor(logger, baseDir) {
         this.logger = logger ?? createLogger({ component: 'marketplace-manager', minimal: true });
+        const dir = baseDir || CONFIG_DIR;
+        this.configDir = dir;
+        this.configFile = path.join(dir, 'marketplaces.json');
+        this.cacheDir = path.join(dir, '.cache', 'marketplaces');
+        this.metadataFile = path.join(dir, '.metadata.json');
     }
     async initialize() {
-        await fs.mkdir(CONFIG_DIR, { recursive: true });
-        await fs.mkdir(CACHE_DIR, { recursive: true });
-        if (existsSync(CONFIG_FILE)) {
-            const data = await fs.readFile(CONFIG_FILE, 'utf-8');
+        await fs.mkdir(this.configDir, { recursive: true });
+        await fs.mkdir(this.cacheDir, { recursive: true });
+        if (existsSync(this.configFile)) {
+            const data = await fs.readFile(this.configFile, 'utf-8');
             try {
                 this.config = JSON.parse(data);
             }
@@ -103,7 +128,7 @@ export class MarketplaceManager {
         }
     }
     async save() {
-        await fs.writeFile(CONFIG_FILE, JSON.stringify(this.config, null, 2), 'utf-8');
+        await fs.writeFile(this.configFile, JSON.stringify(this.config, null, 2), 'utf-8');
     }
     /**
      * Get all marketplaces
@@ -325,7 +350,7 @@ export class MarketplaceManager {
      * Get cache file path for marketplace
      */
     getCacheFile(marketplaceName) {
-        return path.join(CACHE_DIR, `${marketplaceName}.json`);
+        return path.join(this.cacheDir, `${marketplaceName}.json`);
     }
     /**
      * Fetch photons.json manifest from various sources
@@ -563,11 +588,30 @@ export class MarketplaceManager {
                     }
                     const metadata = manifest?.photons.find((p) => p.name === mcpName);
                     // Security: verify content hash if metadata provides one
-                    if (metadata?.hash && marketplace.sourceType !== 'local') {
-                        const expectedHash = metadata.hash.replace(/^sha256:/, '');
+                    // Prefer contentHash (source-only) for download verification; fall back to hash
+                    let verifyHash = metadata?.contentHash || metadata?.hash;
+                    if (verifyHash && marketplace.sourceType !== 'local') {
+                        const expectedHash = verifyHash.replace(/^sha256:/, '');
                         if (!verifyContentHash(content, expectedHash)) {
-                            this.logger.warn(`Content hash mismatch for ${mcpName} — skipping`);
-                            continue;
+                            // Hash mismatch may mean local cache is stale — refresh and retry once
+                            this.logger.info(`Content hash mismatch for ${mcpName} — refreshing manifest cache`);
+                            const updated = await this.updateMarketplaceCache(marketplace.name);
+                            if (updated) {
+                                const freshManifest = await this.getCachedManifest(marketplace.name);
+                                const freshMeta = freshManifest?.photons.find((p) => p.name === mcpName);
+                                verifyHash = freshMeta?.contentHash || freshMeta?.hash;
+                                if (verifyHash) {
+                                    const freshHash = verifyHash.replace(/^sha256:/, '');
+                                    if (!verifyContentHash(content, freshHash)) {
+                                        this.logger.warn(`Content hash mismatch for ${mcpName} after cache refresh — skipping`);
+                                        continue;
+                                    }
+                                }
+                            }
+                            else {
+                                this.logger.warn(`Content hash mismatch for ${mcpName} — skipping`);
+                                continue;
+                            }
                         }
                     }
                     return { content, marketplace, metadata };
@@ -783,29 +827,92 @@ export class MarketplaceManager {
         }
         return [];
     }
+    /**
+     * Install a photon and its assets to the working directory.
+     *
+     * This is the canonical installation path — used by both CLI and Beam UI.
+     * Handles writing the .photon.ts file, saving metadata, and downloading
+     * all declared asset files (UI templates, etc.) with path-traversal protection.
+     *
+     * @param result - The result from fetchMCP()
+     * @param name - Photon name (used for filename)
+     * @param workingDir - Directory to install into (e.g., ~/.photon)
+     * @returns Installed file path and list of asset paths written
+     */
+    async installPhoton(result, name, workingDir) {
+        // Inject @forkedFrom tag if not already present
+        let content = result.content;
+        if (!content.includes('@forkedFrom')) {
+            const origin = `${result.marketplace.repo}#${name}`;
+            // Insert before the first closing */ of the file-level docblock
+            content = content.replace(/(\s*\*\/)/, `\n * @forkedFrom ${origin}$1`);
+        }
+        // Write the .photon.ts file
+        await fs.mkdir(workingDir, { recursive: true });
+        const photonPath = path.join(workingDir, `${name}.photon.ts`);
+        await fs.writeFile(photonPath, content, 'utf-8');
+        const assetsInstalled = [];
+        if (result.metadata) {
+            // Download and save all declared assets first (before hashing)
+            if (result.metadata.assets && result.metadata.assets.length > 0) {
+                const assets = await this.fetchAssets(result.marketplace, result.metadata.assets);
+                for (const [assetPath, content] of assets) {
+                    const safePath = validateAssetPath(assetPath);
+                    const assetTarget = path.join(workingDir, safePath);
+                    if (!isPathWithin(assetTarget, workingDir))
+                        continue;
+                    await fs.mkdir(path.dirname(assetTarget), { recursive: true });
+                    await fs.writeFile(assetTarget, content, 'utf-8');
+                    assetsInstalled.push(assetPath);
+                }
+            }
+            // Save install metadata — use combined hash (source+assets) for update detection
+            // The manifest's `hash` field is the combined hash; fall back to content-only hash
+            const combinedHash = result.metadata.hash || calculateHash(result.content);
+            await this.savePhotonMetadata(`${name}.photon.ts`, result.marketplace, result.metadata, combinedHash);
+        }
+        return { photonPath, assetsInstalled };
+    }
     /**
      * Save installation metadata for a Photon
      */
-    async savePhotonMetadata(fileName, marketplace, metadata, contentHash) {
-        const localMetadata = await readLocalMetadata();
+    async savePhotonMetadata(fileName, marketplace, metadata, combinedHash) {
+        const localMetadata = await this.readMetadata();
         localMetadata.photons[fileName] = {
             marketplace: marketplace.name,
             marketplaceRepo: marketplace.repo,
             version: metadata.version,
-            originalHash: metadata.hash || contentHash,
+            originalHash: combinedHash,
             installedAt: new Date().toISOString(),
         };
-        await writeLocalMetadata(localMetadata);
+        await this.writeMetadata(localMetadata);
     }
     /**
      * Get local installation metadata for a Photon
      */
     async getPhotonInstallMetadata(fileName) {
-        const localMetadata = await readLocalMetadata();
+        const localMetadata = await this.readMetadata();
         return localMetadata.photons[fileName] || null;
     }
+    async readMetadata() {
+        try {
+            if (existsSync(this.metadataFile)) {
+                const data = await fs.readFile(this.metadataFile, 'utf-8');
+                return JSON.parse(data);
+            }
+        }
+        catch {
+            /* corrupted — start fresh */
+        }
+        return { photons: {} };
+    }
+    async writeMetadata(metadata) {
+        await fs.mkdir(this.configDir, { recursive: true });
+        await fs.writeFile(this.metadataFile, JSON.stringify(metadata, null, 2), 'utf-8');
+    }
     /**
      * Check if a Photon file has been modified since installation
+     * Compares combined hash (source + assets) against stored originalHash
      */
     async isPhotonModified(filePath, fileName) {
         const metadata = await this.getPhotonInstallMetadata(fileName);
@@ -813,8 +920,31 @@ export class MarketplaceManager {
             return false; // No metadata, can't determine
         }
         try {
-            const currentHash = await calculateFileHash(filePath);
-            return currentHash !== metadata.originalHash;
+            // Strip @forkedFrom from source (injected during install, not in manifest)
+            const rawContent = await fs.readFile(filePath, 'utf-8');
+            const strippedContent = rawContent.replace(/\n\s*\*\s*@forkedFrom\s+[^\n]+/, '');
+            // Write stripped content to temp for hashing, then compute combined hash
+            // For efficiency, hash inline: source (stripped) + assets
+            const workingDir = path.dirname(filePath);
+            const photonName = fileName.replace(/\.photon\.ts$/, '');
+            // Look up assets from manifest
+            const photonMeta = await this.getPhotonMetadata(photonName);
+            const assets = photonMeta?.metadata.assets;
+            const hasher = crypto.createHash('sha256');
+            hasher.update(strippedContent);
+            if (assets && assets.length > 0) {
+                for (const asset of [...assets].sort()) {
+                    const assetPath = path.join(workingDir, asset);
+                    try {
+                        hasher.update(await fs.readFile(assetPath));
+                    }
+                    catch {
+                        // Asset missing — skip
+                    }
+                }
+            }
+            const hash = `sha256:${hasher.digest('hex')}`;
+            return hash !== metadata.originalHash;
         }
         catch {
             return false; // file unreadable → not modified
@@ -947,6 +1077,320 @@ export class MarketplaceManager {
             recommendation,
         };
     }
+    /**
+     * Get marketplace sources suitable as fork targets
+     */
+    async getForkTargets() {
+        const all = this.getAll();
+        return all
+            .filter((m) => m.sourceType === 'github' && m.repo)
+            .map((m) => ({ name: m.name, repo: m.repo, sourceType: m.sourceType }));
+    }
+    /**
+     * Fork a photon — remove marketplace tracking, optionally push to a target repo.
+     * Shared logic used by both CLI and Beam.
+     */
+    async forkPhoton(name, workingDir, options) {
+        const fileName = `${name}.photon.ts`;
+        const filePath = path.join(workingDir, fileName);
+        // Check file exists
+        if (!existsSync(filePath)) {
+            return { success: false, message: `Photon not found: ${name}` };
+        }
+        // Read install metadata
+        const localMetadata = await readLocalMetadata();
+        const installMeta = localMetadata.photons[fileName];
+        if (!installMeta) {
+            return {
+                success: true,
+                message: `${name} is already a local photon (no marketplace tracking)`,
+            };
+        }
+        // Check @forkedFrom tag
+        const content = await fs.readFile(filePath, 'utf-8');
+        const hasForkedFrom = content.includes('@forkedFrom');
+        // Handle target repo push if specified
+        if (options?.targetRepo || options?.createRepo) {
+            const { execSync } = await import('child_process');
+            // Check gh CLI
+            try {
+                execSync('gh --version', { stdio: 'pipe' });
+            }
+            catch {
+                return {
+                    success: false,
+                    message: 'GitHub CLI (gh) is required but not installed',
+                };
+            }
+            if (options.createRepo) {
+                // Create new repo and push
+                try {
+                    execSync(`gh repo create ${options.createRepo} --public --confirm`, { stdio: 'pipe' });
+                }
+                catch {
+                    // Repo may already exist
+                }
+                const targetRepo = options.createRepo;
+                const tmpDir = path.join(os.tmpdir(), `photon-fork-${Date.now()}`);
+                try {
+                    execSync(`gh repo clone ${targetRepo} "${tmpDir}" -- --depth=1`, {
+                        stdio: 'pipe',
+                    });
+                    await fs.copyFile(filePath, path.join(tmpDir, fileName));
+                    // Copy assets
+                    const photonMeta = await this.getPhotonMetadata(name);
+                    if (photonMeta?.metadata.assets) {
+                        for (const asset of photonMeta.metadata.assets) {
+                            const srcAsset = path.join(workingDir, asset);
+                            if (existsSync(srcAsset)) {
+                                const dstAsset = path.join(tmpDir, asset);
+                                await fs.mkdir(path.dirname(dstAsset), { recursive: true });
+                                await fs.copyFile(srcAsset, dstAsset);
+                            }
+                        }
+                    }
+                    execSync(`cd "${tmpDir}" && git add -A && git commit -m "fork: ${name} photon" && git push origin`, { stdio: 'pipe' });
+                    await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => { });
+                }
+                catch (e) {
+                    await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => { });
+                    return {
+                        success: false,
+                        message: `Failed to push to new repo: ${e.message}`,
+                    };
+                }
+            }
+            else if (options.targetRepo) {
+                // Push to existing repo
+                const tmpDir = path.join(os.tmpdir(), `photon-fork-${Date.now()}`);
+                try {
+                    execSync(`gh repo clone ${options.targetRepo} "${tmpDir}" -- --depth=1`, {
+                        stdio: 'pipe',
+                    });
+                    await fs.copyFile(filePath, path.join(tmpDir, fileName));
+                    // Copy assets
+                    const photonMeta = await this.getPhotonMetadata(name);
+                    if (photonMeta?.metadata.assets) {
+                        for (const asset of photonMeta.metadata.assets) {
+                            const srcAsset = path.join(workingDir, asset);
+                            if (existsSync(srcAsset)) {
+                                const dstAsset = path.join(tmpDir, asset);
+                                await fs.mkdir(path.dirname(dstAsset), { recursive: true });
+                                await fs.copyFile(srcAsset, dstAsset);
+                            }
+                        }
+                    }
+                    execSync(`cd "${tmpDir}" && git add -A && git commit -m "fork: ${name} photon" && git push origin`, { stdio: 'pipe' });
+                    await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => { });
+                }
+                catch (e) {
+                    await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => { });
+                    return {
+                        success: false,
+                        message: `Failed to push to ${options.targetRepo}: ${e.message}`,
+                    };
+                }
+            }
+        }
+        // Remove marketplace tracking
+        delete localMetadata.photons[fileName];
+        await this.writeMetadata(localMetadata);
+        const parts = [];
+        parts.push(`${name} is now your own`);
+        if (hasForkedFrom) {
+            parts.push('Origin preserved as @forkedFrom tag');
+        }
+        parts.push('Marketplace update tracking removed');
+        return { success: true, message: parts.join('. ') };
+    }
+    /**
+     * Contribute a photon back upstream via PR.
+     * Shared logic used by both CLI and Beam.
+     */
+    async contributePhoton(name, workingDir, options) {
+        const { execSync } = await import('child_process');
+        const fileName = `${name}.photon.ts`;
+        const filePath = path.join(workingDir, fileName);
+        // Check file exists
+        if (!existsSync(filePath)) {
+            return { success: false, message: `Photon not found: ${name}` };
+        }
+        // Check gh CLI
+        try {
+            execSync('gh --version', { stdio: 'pipe' });
+        }
+        catch {
+            return {
+                success: false,
+                message: 'GitHub CLI (gh) is required. Install: https://cli.github.com/',
+            };
+        }
+        // Check gh auth
+        try {
+            execSync('gh auth status', { stdio: 'pipe' });
+        }
+        catch {
+            return {
+                success: false,
+                message: 'GitHub CLI is not authenticated. Run: gh auth login',
+            };
+        }
+        // Read install metadata
+        const localMetadata = await readLocalMetadata();
+        const installMeta = localMetadata.photons[fileName];
+        if (!installMeta) {
+            return {
+                success: false,
+                message: `${name} was not installed from a marketplace`,
+            };
+        }
+        if (!installMeta.marketplaceRepo) {
+            return {
+                success: false,
+                message: `No upstream repository found for ${name}`,
+            };
+        }
+        // Check if actually modified
+        const modified = await this.isPhotonModified(filePath, fileName);
+        if (!modified) {
+            return {
+                success: true,
+                message: `${name} has not been modified — nothing to contribute`,
+            };
+        }
+        const repo = installMeta.marketplaceRepo;
+        const branchName = options?.branch || `contribute/${name}-${Date.now()}`;
+        if (options?.dryRun) {
+            return {
+                success: true,
+                message: [
+                    `[dry-run] Would:`,
+                    `  1. Fork ${repo}`,
+                    `  2. Clone fork to temp directory`,
+                    `  3. Copy modified ${fileName} (and assets)`,
+                    `  4. Create branch ${branchName}`,
+                    `  5. Commit and push`,
+                    `  6. Create PR to ${repo}`,
+                ].join('\n'),
+            };
+        }
+        // Fork the repo
+        try {
+            execSync(`gh repo fork ${repo} --clone=false`, { stdio: 'pipe' });
+        }
+        catch {
+            // Fork may already exist
+        }
+        // Get fork name
+        const forkJson = execSync('gh api user', { encoding: 'utf-8' });
+        const ghUser = JSON.parse(forkJson).login;
+        const repoName = repo.split('/')[1];
+        const forkRepo = `${ghUser}/${repoName}`;
+        // Clone to temp dir
+        const tmpDir = path.join(os.tmpdir(), `photon-contribute-${Date.now()}`);
+        try {
+            execSync(`gh repo clone ${forkRepo} "${tmpDir}" -- --depth=1`, {
+                stdio: 'pipe',
+            });
+            // Copy modified photon file
+            await fs.copyFile(filePath, path.join(tmpDir, fileName));
+            // Copy assets
+            const photonMeta = await this.getPhotonMetadata(name);
+            if (photonMeta?.metadata.assets) {
+                for (const asset of photonMeta.metadata.assets) {
+                    const srcAsset = path.join(workingDir, asset);
+                    if (existsSync(srcAsset)) {
+                        const dstAsset = path.join(tmpDir, asset);
+                        await fs.mkdir(path.dirname(dstAsset), { recursive: true });
+                        await fs.copyFile(srcAsset, dstAsset);
+                    }
+                }
+            }
+            // Create branch, commit, push
+            execSync(`cd "${tmpDir}" && git checkout -b "${branchName}" && git add -A && git commit -m "improve: update ${name} photon" && git push origin "${branchName}"`, { stdio: 'pipe' });
+            // Create PR
+            const prOutput = execSync(`cd "${tmpDir}" && gh pr create --repo "${repo}" --title "Improve ${name} photon" --body "Contributed improvements to ${name} photon via Photon marketplace."`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+            // Cleanup temp dir
+            await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => { });
+            const prUrl = prOutput.trim();
+            return {
+                success: true,
+                prUrl,
+                message: `Pull request created: ${prUrl}`,
+            };
+        }
+        catch (e) {
+            await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => { });
+            return {
+                success: false,
+                message: `Contribute failed: ${e.message}`,
+            };
+        }
+    }
+    /**
+     * Resolve and install a photon from a GitHub shorthand reference.
+     * Format: owner/repo  (photon name = repo name)
+     *      or owner/repo/photon-name
+     *
+     * - Adds the marketplace to config (idempotent)
+     * - Fetches and installs the photon to workingDir
+     * - If already installed, skips fetch
+     * - Returns the resolved photon name
+     */
+    async fetchAndInstallFromRef(ref, workingDir) {
+        const parts = ref.split('/');
+        let owner, repo, photonName;
+        if (parts.length === 2) {
+            [owner, repo] = parts;
+            photonName = repo;
+        }
+        else if (parts.length === 3) {
+            [owner, repo, photonName] = parts;
+        }
+        else {
+            throw new Error(`Invalid photon reference: ${ref}. Expected owner/repo or owner/repo/photon-name`);
+        }
+        const photonFile = path.join(workingDir, `${photonName}.photon.ts`);
+        // Already installed — skip fetch
+        if (existsSync(photonFile)) {
+            return { photonName, alreadyInstalled: true };
+        }
+        // Add marketplace (idempotent — skips if already added)
+        const repoShorthand = `${owner}/${repo}`;
+        const { marketplace: marketplaceInfo } = await this.add(repoShorthand);
+        // Fetch photon content directly from GitHub raw
+        const rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/main/${photonName}.photon.ts`;
+        let content;
+        try {
+            const response = await fetch(rawUrl, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            content = await response.text();
+        }
+        catch (err) {
+            throw new Error(`Could not fetch photon '${photonName}' from ${repoShorthand}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Try to get manifest metadata (best-effort)
+        const marketplace = this.get(marketplaceInfo.name);
+        if (!marketplace)
+            throw new Error(`Marketplace not found after add: ${marketplaceInfo.name}`);
+        await this.updateMarketplaceCache(marketplace.name).catch(() => {
+            /* non-fatal */
+        });
+        const manifest = await this.getCachedManifest(marketplace.name);
+        const metadata = manifest?.photons.find((p) => p.name === photonName);
+        // When no manifest exists, use a minimal synthetic metadata so that
+        // .metadata.json is always written (enables update detection via hash comparison)
+        const effectiveMetadata = metadata ?? {
+            name: photonName,
+            version: 'unknown',
+            description: '',
+            source: rawUrl,
+        };
+        await this.installPhoton({ content, marketplace, metadata: effectiveMetadata }, photonName, workingDir);
+        return { photonName, alreadyInstalled: false };
+    }
     /**
      * Compare two semver versions
      * Returns: positive if v1 > v2, negative if v1 < v2, 0 if equal