@portel/photon 1.4.1 → 1.6.0

package/dist/loader.d.ts

@@ -3,24 +3,63 @@
  *
  * Loads a single .photon.ts file and extracts tools
  */
-import { PhotonMCPClass, PhotonMCPClassExtended } from '@portel/photon-core';
+import { ConstructorParam, PhotonMCPClass, PhotonMCPClassExtended, type InputProvider, type OutputHandler, type MCPClientFactory } from '@portel/photon-core';
+import { Logger } from './shared/logger.js';
 export declare class PhotonLoader {
     private dependencyManager;
     private verbose;
-    constructor(verbose?: boolean);
+    private mcpClientFactory?;
+    /** Cache of loaded Photon instances by source path */
+    private loadedPhotons;
+    /** MCP clients cache - reuse connections */
+    private mcpClients;
+    /** SDK factory for MCP connections */
+    private sdkFactory?;
+    /** Cached MCP config from ~/.photon/config.json */
+    private mcpConfig?;
+    /** Progress renderer for inline CLI animation */
+    private progressRenderer;
+    /** Marketplace manager for resolving remote Photons */
+    private marketplaceManager?;
+    private marketplaceManagerPromise?;
+    private logger;
+    constructor(verbose?: boolean, logger?: Logger);
+    /**
+     * Load MCP configuration from ~/.photon/config.json
+     * Called lazily on first MCP injection
+     */
+    private ensureMCPConfig;
+    private getMarketplaceManager;
+    /**
+     * Set MCP client factory for enabling this.mcp() in Photons
+     */
+    setMCPClientFactory(factory: MCPClientFactory): void;
     /**
      * Log message only if verbose mode is enabled
      */
     private log;
+    /**
+     * Generate deterministic cache key for an MCP + photon path
+     */
+    private getCacheKey;
+    private getPhotonCacheDir;
+    private sanitizeCacheLabel;
+    private writePhotonCacheFile;
+    private runCommand;
     /**
      * Directory where MCP-specific dependencies are cached
      */
     private getDependencyCacheDir;
+    private getBuildCacheDir;
+    private clearBuildCache;
+    private clearDependencyCache;
+    private clearAllCaches;
     /**
      * Path to metadata file describing installed dependencies
      */
     private getDependencyMetadataPath;
     private readDependencyMetadata;
+    private pathExists;
     private dependenciesEqual;
     private writeDependencyMetadata;
     private ensureDependenciesWithHash;
@@ -37,19 +76,22 @@ export declare class PhotonLoader {
     reloadFile(filePath: string): Promise<PhotonMCPClassExtended>;
     /**
      * Compile TypeScript file to JavaScript and cache it
+     * Delegates to shared compilePhotonTS from photon-core
      */
     private compileTypeScript;
     /**
      * Find the MCP class in a module
-     * Looks for default export or any class with async methods
+     * Delegates to shared findPhotonClass from photon-core
      */
     private findMCPClass;
     /**
      * Check if a function is a class constructor
+     * Delegates to shared isClass from photon-core
      */
     private isClass;
     /**
      * Check if a class has async methods
+     * Delegates to shared hasAsyncMethods from photon-core
      */
     private hasAsyncMethods;
     /**
@@ -67,45 +109,173 @@ export declare class PhotonLoader {
     /**
      * Extract constructor parameters from source file
      */
-    private extractConstructorParams;
+    extractConstructorParams(filePath: string): Promise<ConstructorParam[]>;
     /**
-     * Resolve constructor arguments from environment variables
+     * Resolve all constructor injections using type-based detection
+     * - Primitives (string, number, boolean) → env var
+     * - Non-primitives matching @mcp → MCP client
+     * - Non-primitives matching @photon → Photon instance
+     *
+     * Throws MCPConfigurationError if MCP dependencies are missing
      */
-    private resolveConstructorArgs;
+    private resolveAllInjections;
     /**
-     * Convert MCP name and parameter name to environment variable name
-     * Example: filesystem, workdir → FILESYSTEM_WORKDIR
+     * Get or create an MCP client for a dependency
+     *
+     * Resolution order:
+     * 1. Check ~/.photon/config.json for configured server
+     * 2. Fall back to resolving from @mcp declaration source
+     *
+     * Validates connection on first use - throws MCPConfigurationError if connection fails
      */
-    private toEnvVarName;
+    private getMCPClient;
     /**
-     * Parse environment variable value based on TypeScript type
+     * Get or load a Photon instance for a dependency
      */
-    private parseEnvValue;
+    private getPhotonInstance;
     /**
-     * Enhance constructor error with configuration guidance
+     * Resolve Photon dependency path based on source type
      */
-    private enhanceConstructorError;
+    private resolvePhotonPath;
+    private resolveMarketplacePhoton;
+    private normalizeMarketplaceSource;
+    private fetchPhotonFromMarketplace;
+    private fetchPhotonFromSpecificMarketplace;
+    private fetchGithubPhoton;
+    private parseGithubSource;
+    private resolveNpmPhoton;
+    private parseNpmSource;
+    private extractPackageName;
+    private getPackageInstallPath;
+    private ensureNpmPackageInstalled;
+    private findPhotonFile;
     /**
-     * Generate helpful example values based on parameter name and type
+     * Resolve constructor arguments from environment variables
+     * @deprecated Use resolveAllInjections instead
      */
-    private generateExampleValue;
+    private resolveConstructorArgs;
     /**
-     * Generate user-friendly configuration error message
+     * Parse environment variable value based on TypeScript type
+     * Delegates to shared parseEnvValue from photon-core
+     */
+    private parseEnvValue;
+    /**
+     * Enhance constructor error with configuration guidance
      */
-    private generateConfigErrorMessage;
+    private enhanceConstructorError;
     /**
      * Execute a tool on the loaded MCP instance
      * Handles both regular async methods and async generators
+     *
+     * For generators with checkpoint yields, automatically uses stateful execution
+     * with JSONL persistence. The run ID is returned in the result for stateful workflows.
+     *
+     * @param mcp - The loaded Photon MCP
+     * @param toolName - Name of the tool to execute
+     * @param parameters - Input parameters for the tool
+     * @param options - Optional execution options
+     * @returns Tool result, or wrapped result with runId for stateful workflows
      */
-    executeTool(mcp: PhotonMCPClass, toolName: string, parameters: any): Promise<any>;
+    executeTool(mcp: PhotonMCPClass, toolName: string, parameters: any, options?: {
+        resumeRunId?: string;
+        outputHandler?: OutputHandler;
+        inputProvider?: InputProvider;
+    }): Promise<any>;
     /**
-     * Create an input provider for generator yields
-     * Uses the global prompt handler or falls back to native dialogs
+     * Create an input provider for generator ask yields
+     * Supports the new ask/emit pattern from photon-core 1.2.0
      */
     private createInputProvider;
     /**
-     * Create an output handler for generator yields (progress, stream, log)
+     * Create an output handler for generator emit yields
+     * Supports the new ask/emit pattern from photon-core 1.2.0
+     * Uses inline progress animation for CLI
      */
     private createOutputHandler;
+    /**
+     * Auto-wire ReactiveArray/Map/Set properties for zero-boilerplate reactivity
+     *
+     * When a photon developer imports { Array } from '@portel/photon-core',
+     * it shadows the global Array. The runtime then auto-wires these properties:
+     * - Sets _propertyName to the property key (e.g., 'items')
+     * - Sets _emitter to instance.emit.bind(instance)
+     *
+     * This enables the pattern:
+     * ```typescript
+     * import { Array } from '@portel/photon-core';
+     *
+     * export default class TodoList {
+     *   items: Array<Task> = [];  // Just use it normally
+     *
+     *   add(text: string) {
+     *     this.items.push({ id: crypto.randomUUID(), text });
+     *     // Auto-emits 'items:added' - no manual wiring needed!
+     *   }
+     * }
+     * ```
+     */
+    private wireReactiveCollections;
+    /**
+     * Extract @mcp dependencies from source and inject them as instance properties
+     *
+     * This enables the pattern:
+     * ```typescript
+     * /**
+     *  * @mcp github anthropics/mcp-server-github
+     *  *\/
+     * export default class MyPhoton extends PhotonMCP {
+     *   async doSomething() {
+     *     const issues = await this.github.list_issues({ repo: 'owner/repo' });
+     *   }
+     * }
+     * ```
+     */
+    private injectMCPDependencies;
+    /**
+     * Check CLI dependencies declared via @cli tags
+     *
+     * Validates that required command-line tools are available on the system.
+     * Throws a helpful error with install URLs if any are missing.
+     *
+     * Format: @cli <name> - <install_url>
+     *
+     * Example:
+     * ```typescript
+     * /**
+     *  * @cli git - https://git-scm.com/downloads
+     *  * @cli ffmpeg - https://ffmpeg.org/download.html
+     *  *\/
+     * ```
+     */
+    private checkCLIDependencies;
+    /**
+     * Check if a CLI command exists on the system
+     */
+    private checkCLIExists;
+    /**
+     * Discover and extract assets from a Photon file
+     * Uses shared discoverAssets from photon-core for core logic,
+     * then applies photon-specific extensions (method UI links, URI generation).
+     */
+    private discoverAssets;
+    /**
+     * Generate ui:// URIs for all UI assets (MCP Apps Extension support)
+     * URI format: ui://<photon-name>/<asset-id>
+     */
+    private generateAssetURIs;
+    /**
+     * Apply method-level @ui annotations to link UI assets to tools
+     * Called after auto-discovery so all UI assets are available
+     */
+    private applyMethodUILinks;
+    /**
+     * Check if a file exists
+     */
+    private fileExists;
+    /**
+     * Get MIME type from file extension
+     * Delegates to shared getMimeType from photon-core
+     */
+    private getMimeType;
 }
 //# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,EAKL,cAAc,EACd,sBAAsB,EAcvB,MAAM,qBAAqB,CAAC;AAQ7B,qBAAa,YAAY;IACvB,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,OAAO,CAAU;gBAEb,OAAO,GAAE,OAAe;IAKpC;;OAEG;IACH,OAAO,CAAC,GAAG;IAMX;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAI7B;;OAEG;IACH,OAAO,CAAC,yBAAyB;YAInB,sBAAsB;IASpC,OAAO,CAAC,iBAAiB;YAYX,uBAAuB;YAMvB,0BAA0B;IAwBxC,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,MAAM,CAAC,2BAA2B;IAqB1C,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAWnC;;OAEG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAiIjE;;OAEG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAuBnE;;OAEG;YACW,iBAAiB;IAuC/B;;;OAGG;IACH,OAAO,CAAC,YAAY;IAkBpB;;OAEG;IACH,OAAO,CAAC,OAAO;IAIf;;OAEG;IACH,OAAO,CAAC,eAAe;IAmBvB;;OAEG;IACH,OAAO,CAAC,UAAU;IAelB;;OAEG;IACH,OAAO,CAAC,cAAc;IA0BtB;;OAEG;YACW,YAAY;IAgG1B;;OAEG;YACW,wBAAwB;IAWtC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAoC9B;;;OAGG;IACH,OAAO,CAAC,YAAY;IASpB;;OAEG;IACH,OAAO,CAAC,aAAa;IAYrB;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAkF/B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA2D5B;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAuClC;;;OAGG;IACG,WAAW,CAAC,GAAG,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IAsCvF;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IA6B3B;;OAEG;IACH,OAAO,CAAC,mBAAmB;CAiB5B"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"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"}