npm - @portel/photon-core - Versions diffs - 2.2.0 → 2.4.0 - Mend

@portel/photon-core 2.2.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (75) hide show

package/dist/asset-discovery.d.ts +25 -0
package/dist/asset-discovery.d.ts.map +1 -0
package/dist/asset-discovery.js +144 -0
package/dist/asset-discovery.js.map +1 -0
package/dist/base.d.ts +1 -1
package/dist/base.d.ts.map +1 -1
package/dist/base.js +12 -6
package/dist/base.js.map +1 -1
package/dist/class-detection.d.ts +32 -0
package/dist/class-detection.d.ts.map +1 -0
package/dist/class-detection.js +86 -0
package/dist/class-detection.js.map +1 -0
package/dist/compiler.d.ts +22 -0
package/dist/compiler.d.ts.map +1 -0
package/dist/compiler.js +48 -0
package/dist/compiler.js.map +1 -0
package/dist/config.d.ts +63 -0
package/dist/config.d.ts.map +1 -0
package/dist/config.js +117 -0
package/dist/config.js.map +1 -0
package/dist/design-system/tokens.d.ts +66 -0
package/dist/design-system/tokens.d.ts.map +1 -1
package/dist/design-system/tokens.js +324 -44
package/dist/design-system/tokens.js.map +1 -1
package/dist/env-utils.d.ts +61 -0
package/dist/env-utils.d.ts.map +1 -0
package/dist/env-utils.js +171 -0
package/dist/env-utils.js.map +1 -0
package/dist/index.d.ts +9 -0
package/dist/index.d.ts.map +1 -1
package/dist/index.js +27 -0
package/dist/index.js.map +1 -1
package/dist/mcp-apps.d.ts +130 -0
package/dist/mcp-apps.d.ts.map +1 -0
package/dist/mcp-apps.js +87 -0
package/dist/mcp-apps.js.map +1 -0
package/dist/mime-types.d.ts +13 -0
package/dist/mime-types.d.ts.map +1 -0
package/dist/mime-types.js +47 -0
package/dist/mime-types.js.map +1 -0
package/dist/rendering/index.d.ts +49 -0
package/dist/rendering/index.d.ts.map +1 -1
package/dist/rendering/index.js +153 -0
package/dist/rendering/index.js.map +1 -1
package/dist/schema-extractor.d.ts +18 -1
package/dist/schema-extractor.d.ts.map +1 -1
package/dist/schema-extractor.js +81 -11
package/dist/schema-extractor.js.map +1 -1
package/dist/types.d.ts +75 -0
package/dist/types.d.ts.map +1 -1
package/dist/types.js.map +1 -1
package/dist/validation.d.ts +51 -0
package/dist/validation.d.ts.map +1 -0
package/dist/validation.js +249 -0
package/dist/validation.js.map +1 -0
package/dist/version-check.d.ts +22 -0
package/dist/version-check.d.ts.map +1 -0
package/dist/version-check.js +91 -0
package/dist/version-check.js.map +1 -0
package/package.json +12 -2
package/src/asset-discovery.ts +160 -0
package/src/base.ts +12 -5
package/src/class-detection.ts +94 -0
package/src/compiler.ts +57 -0
package/src/config.ts +134 -0
package/src/design-system/tokens.ts +381 -57
package/src/env-utils.ts +216 -0
package/src/index.ts +106 -0
package/src/mcp-apps.ts +204 -0
package/src/mime-types.ts +49 -0
package/src/rendering/index.ts +197 -0
package/src/schema-extractor.ts +95 -12
package/src/types.ts +82 -0
package/src/validation.ts +363 -0
package/src/version-check.ts +92 -0

package/src/rendering/index.ts CHANGED Viewed

@@ -19,6 +19,8 @@ export * from './field-renderers.js';
 export * from './template-engine.js';
 export * from '../design-system/index.js';
+import { analyzeFields, type FieldMapping } from './field-analyzer.js';
+import { selectLayout, type LayoutType } from './layout-selector.js';
 import { generateFieldAnalyzerJS } from './field-analyzer.js';
 import { generateLayoutSelectorJS } from './layout-selector.js';
 import { generateComponentsJS, generateComponentCSS } from './components.js';
@@ -61,3 +63,198 @@ export function generateSmartRenderingCSS(): string {
     generateTemplateEngineCSS(),
   ].join('\n');
 }
+// ===== Smart Rendering Utilities =====
+// Shared by NCP, Lumina, and other runtimes
+/**
+ * Check if data would benefit from rich HTML rendering
+ * (arrays of objects, nested structures, etc.)
+ */
+export function shouldUseRichRendering(data: any): boolean {
+  if (!data) return false;
+  // Arrays of objects benefit from list/grid rendering
+  if (Array.isArray(data) && data.length > 0 && typeof data[0] === 'object') {
+    return true;
+  }
+  // Nested objects benefit from tree/card rendering
+  if (typeof data === 'object' && !Array.isArray(data)) {
+    const values = Object.values(data);
+    if (values.some(v => typeof v === 'object' && v !== null)) {
+      return true;
+    }
+  }
+  return false;
+}
+/**
+ * Generate an HTML content block for MCP tool responses.
+ * Analyses data, selects layout, and embeds CSS/JS for rich rendering.
+ */
+export function generateHTMLContent(
+  data: any,
+  options: {
+    title?: string;
+    format?: LayoutType;
+    standalone?: boolean;
+    theme?: 'light' | 'dark';
+  } = {}
+): string {
+  const { title, format, standalone = false, theme } = options;
+  let fieldMapping: FieldMapping | undefined;
+  if (data && typeof data === 'object') {
+    fieldMapping = analyzeFields(data);
+  }
+  const layout = format || selectLayout(data);
+  const renderScript = `
+    <script>
+      ${generateSmartRenderingJS()}
+      document.addEventListener('DOMContentLoaded', function() {
+        const container = document.getElementById('smart-render-container');
+        const data = ${JSON.stringify(data)};
+        const layout = '${layout}';
+        const fieldMapping = ${JSON.stringify(fieldMapping || {})};
+        if (window.TemplateEngine && window.TemplateEngine.render) {
+          container.innerHTML = window.TemplateEngine.render(data, {
+            layout,
+            fieldMapping,
+            title: ${JSON.stringify(title || '')}
+          });
+        } else {
+          container.innerHTML = '<pre>' + JSON.stringify(data, null, 2) + '</pre>';
+        }
+      });
+    </script>
+  `;
+  const themeVars = theme ? `
+    :root {
+      --bg-primary: ${theme === 'dark' ? '#0a0a0a' : '#ffffff'};
+      --text-primary: ${theme === 'dark' ? '#f5f5f5' : '#1a1a1a'};
+    }
+  ` : '';
+  const styles = `
+    <style>
+      ${generateSmartRenderingCSS()}
+      ${themeVars}
+    </style>
+  `;
+  const content = `
+    ${styles}
+    <div id="smart-render-container" class="smart-render">
+      ${title ? `<h2 class="smart-render-title">${title}</h2>` : ''}
+      <div class="loading">Loading...</div>
+    </div>
+    ${renderScript}
+  `;
+  if (standalone) {
+    return `<!DOCTYPE html>
+<html${theme ? ` data-theme="${theme}"` : ''}>
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${title || 'Result'}</title>
+</head>
+<body>
+  ${content}
+</body>
+</html>`;
+  }
+  return content;
+}
+/**
+ * Create an MCP content block with HTML type
+ */
+export function createHTMLContentBlock(
+  data: any,
+  options: {
+    title?: string;
+    format?: LayoutType;
+  } = {}
+): { type: 'text'; text: string; mimeType?: string } {
+  return {
+    type: 'text',
+    text: generateHTMLContent(data, { ...options, standalone: false }),
+    mimeType: 'text/html'
+  };
+}
+/**
+ * Generate an HTML fragment for embedding, returning separate html/css/js parts
+ */
+export function generateSmartRenderFragment(
+  data: any,
+  options: { format?: LayoutType } = {}
+): { html: string; css: string; js: string } {
+  const { format } = options;
+  let fieldMapping: FieldMapping | undefined;
+  if (data && typeof data === 'object') {
+    fieldMapping = analyzeFields(data);
+  }
+  const layout = format || selectLayout(data);
+  const html = `<div id="smart-render-${Date.now()}" class="smart-render-container"></div>`;
+  const css = generateSmartRenderingCSS();
+  const js = `
+    ${generateSmartRenderingJS()}
+    (function() {
+      const containers = document.querySelectorAll('.smart-render-container');
+      const container = containers[containers.length - 1];
+      const data = ${JSON.stringify(data)};
+      if (window.TemplateEngine && window.TemplateEngine.render) {
+        container.innerHTML = window.TemplateEngine.render(data, {
+          layout: '${layout}',
+          fieldMapping: ${JSON.stringify(fieldMapping || {})}
+        });
+      }
+    })();
+  `;
+  return { html, css, js };
+}
+/**
+ * Generate MCP content blocks with smart rendering.
+ * Returns JSON text block + optional HTML block for rich clients.
+ */
+export function generateMCPSmartContent(
+  data: any,
+  options: { includeHtml?: boolean; format?: LayoutType } = {}
+): Array<{ type: string; text?: string; mimeType?: string }> {
+  const { includeHtml = true, format } = options;
+  const content: Array<{ type: string; text?: string; mimeType?: string }> = [];
+  // Always include JSON for compatibility
+  content.push({
+    type: 'text',
+    text: JSON.stringify(data, null, 2)
+  });
+  // Optionally include HTML for rich rendering
+  if (includeHtml && shouldUseRichRendering(data)) {
+    const { html, css, js } = generateSmartRenderFragment(data, { format });
+    content.push({
+      type: 'text',
+      text: `<style>${css}</style>${html}<script>${js}</script>`,
+      mimeType: 'text/html'
+    });
+  }
+  return content;
+}

package/src/schema-extractor.ts CHANGED Viewed

@@ -10,12 +10,14 @@
 import * as fs from 'fs/promises';
 import * as ts from 'typescript';
-import { ExtractedSchema, ConstructorParam, TemplateInfo, StaticInfo, OutputFormat, YieldInfo, MCPDependency, PhotonDependency, ResolvedInjection, PhotonAssets, UIAsset, PromptAsset, ResourceAsset } from './types.js';
+import { ExtractedSchema, ConstructorParam, TemplateInfo, StaticInfo, OutputFormat, YieldInfo, MCPDependency, PhotonDependency, CLIDependency, ResolvedInjection, PhotonAssets, UIAsset, PromptAsset, ResourceAsset, ConfigSchema, ConfigParam } from './types.js';
 export interface ExtractedMetadata {
   tools: ExtractedSchema[];
   templates: TemplateInfo[];
   statics: StaticInfo[];
+  /** Configuration schema from configure() method */
+  configSchema?: ConfigSchema;
 }
 /**
@@ -43,6 +45,13 @@ export class SchemaExtractor {
     const templates: TemplateInfo[] = [];
     const statics: StaticInfo[] = [];
+    // Configuration schema tracking
+    let configSchema: ConfigSchema = {
+      hasConfigureMethod: false,
+      hasGetConfigMethod: false,
+      params: [],
+    };
     try {
       // If source doesn't contain a class declaration, wrap it in one
       let sourceToParse = source;
@@ -67,6 +76,34 @@ export class SchemaExtractor {
           return;
         }
+        // Handle configuration convention methods specially
+        if (methodName === 'configure') {
+          configSchema.hasConfigureMethod = true;
+          const jsdoc = this.getJSDocComment(member, sourceFile);
+          configSchema.description = this.extractDescription(jsdoc);
+          // Extract configure() parameters as config schema
+          const paramsType = this.getFirstParameterType(member, sourceFile);
+          if (paramsType) {
+            const { properties, required } = this.buildSchemaFromType(paramsType, sourceFile);
+            const paramDocs = this.extractParamDocs(jsdoc);
+            configSchema.params = Object.keys(properties).map(name => ({
+              name,
+              type: properties[name].type || 'string',
+              description: paramDocs.get(name) || properties[name].description,
+              required: required.includes(name),
+              defaultValue: properties[name].default,
+            }));
+          }
+          return; // Don't add configure() as a tool
+        }
+        if (methodName === 'getConfig') {
+          configSchema.hasGetConfigMethod = true;
+          return; // Don't add getConfig() as a tool
+        }
         const jsdoc = this.getJSDocComment(member, sourceFile);
         // Check if this is an async generator method (has asterisk token)
@@ -147,6 +184,9 @@ export class SchemaExtractor {
           const scheduled = this.extractScheduled(jsdoc, methodName);
           const locked = this.extractLocked(jsdoc, methodName);
+          // Check for static keyword on the method
+          const isStaticMethod = member.modifiers?.some(m => m.kind === ts.SyntaxKind.StaticKeyword) || false;
           tools.push({
             name: methodName,
             description,
@@ -159,6 +199,7 @@ export class SchemaExtractor {
             ...(yields && yields.length > 0 ? { yields } : {}),
             ...(isStateful ? { isStateful: true } : {}),
             ...(autorun ? { autorun: true } : {}),
+            ...(isStaticMethod ? { isStatic: true } : {}),
             // Daemon features
             ...(webhook !== undefined ? { webhook } : {}),
             ...(scheduled ? { scheduled } : {}),
@@ -188,7 +229,12 @@ export class SchemaExtractor {
       console.error('Failed to parse TypeScript source:', error.message);
     }
-    return { tools, templates, statics };
+    // Only include configSchema if there's a configure() method
+    const result: ExtractedMetadata = { tools, templates, statics };
+    if (configSchema.hasConfigureMethod) {
+      result.configSchema = configSchema;
+    }
+    return result;
   }
   /**
@@ -610,21 +656,24 @@ export class SchemaExtractor {
    * Extract main description from JSDoc comment
    */
   private extractDescription(jsdocContent: string): string {
-    // Split by @param to get only the description part
-    const beforeParams = jsdocContent.split(/@param/)[0];
+    // Split by @param to get only the description part (also stop at other @tags)
+    const beforeTags = jsdocContent.split(/@(?:param|example|returns?|throws?|see|since|deprecated|version|author|license|ui|icon|format|stateful|autorun|webhook|cron|scheduled|locked|Template|Static|mcp|photon|cli|tags|dependencies|csp|visibility)\b/)[0];
     // Remove leading * from each line and trim
-    const lines = beforeParams
+    const lines = beforeTags
       .split('\n')
       .map((line) => line.trim().replace(/^\*\s?/, ''))
-      .filter((line) => line && !line.startsWith('@')); // Exclude @tags and empty lines
+      .filter((line) => line !== ''); // Keep non-empty lines
+    // Take lines up to the first markdown heading (## sections are extended docs)
+    const descLines: string[] = [];
+    for (const line of lines) {
+      if (line.startsWith('#')) break;
+      descLines.push(line);
+    }
-    // Take only the last meaningful line (the actual method description)
-    // This filters out file headers
-    const meaningfulLines = lines.filter(line => line.length > 5); // Filter out short lines
-    const description = meaningfulLines.length > 0
-      ? meaningfulLines[meaningfulLines.length - 1]
-      : lines.join(' ');
+    // Join all description lines into a single string
+    const description = descLines.join(' ');
     // Clean up multiple spaces
     return description.replace(/\s+/g, ' ').trim() || 'No description';
@@ -1376,6 +1425,40 @@ export class SchemaExtractor {
     return 'marketplace';
   }
+  /**
+   * Extract CLI dependencies from source code
+   * Parses @cli tags in file-level or class-level JSDoc comments
+   *
+   * Format: @cli <name> - <install_url>
+   *
+   * Example:
+   * ```
+   * /**
+   *  * @cli git - https://git-scm.com/downloads
+   *  * @cli ffmpeg - https://ffmpeg.org/download.html
+   *  *\/
+   * ```
+   */
+  extractCLIDependencies(source: string): CLIDependency[] {
+    const dependencies: CLIDependency[] = [];
+    // Match @cli <name> or @cli <name> - <url> pattern
+    // The URL is optional
+    const cliRegex = /@cli\s+(\w[\w-]*)\s*(?:-\s*([^\s*@\n]+))?/g;
+    let match;
+    while ((match = cliRegex.exec(source)) !== null) {
+      const [, name, installUrl] = match;
+      dependencies.push({
+        name: name.trim(),
+        installUrl: installUrl?.trim(),
+      });
+    }
+    return dependencies;
+  }
   /**
    * Resolve all injections for a Photon class
    * Determines how each constructor parameter should be injected:

package/src/types.ts CHANGED Viewed

@@ -63,6 +63,8 @@ export interface ExtractedSchema {
   isStateful?: boolean;
   /** True if this method should auto-execute when selected (idempotent, no required params) */
   autorun?: boolean;
+  /** True if this is a static method (class-level, no instance needed) */
+  isStatic?: boolean;
   // ═══ DAEMON FEATURES ═══
@@ -192,6 +194,24 @@ export interface PhotonDependency {
   sourceType: 'marketplace' | 'github' | 'npm' | 'local';
 }
+/**
+ * CLI Dependency - System command-line tool required by a Photon
+ *
+ * Declared via @cli annotation:
+ * ```
+ * /**
+ *  * @cli git - https://git-scm.com/downloads
+ *  * @cli ffmpeg - https://ffmpeg.org/download.html
+ *  *\/
+ * ```
+ */
+export interface CLIDependency {
+  /** CLI command name (e.g., 'git', 'ffmpeg') */
+  name: string;
+  /** Install URL or instructions */
+  installUrl?: string;
+}
 // ════════════════════════════════════════════════════════════════════════════
 // PHOTON ASSETS - Static files referenced via @ui, @prompt, @resource
 // ════════════════════════════════════════════════════════════════════════════
@@ -501,3 +521,65 @@ export interface WorkflowRun {
     ts: number;
   };
 }
+// ══════════════════════════════════════════════════════════════════════════════
+// CONFIGURATION CONVENTION
+// ══════════════════════════════════════════════════════════════════════════════
+/**
+ * Configuration parameter extracted from configure() method
+ */
+export interface ConfigParam {
+  /** Parameter name */
+  name: string;
+  /** Parameter type (string, number, boolean, etc.) */
+  type: string;
+  /** Description from JSDoc */
+  description?: string;
+  /** Whether the parameter is required */
+  required: boolean;
+  /** Default value if any */
+  defaultValue?: any;
+}
+/**
+ * Configuration schema extracted from a Photon's configure() method
+ *
+ * The configure() method is a by-convention method for photon configuration.
+ * Similar to how main() makes a photon a UI application, configure() makes
+ * it a configurable photon.
+ *
+ * When present, the framework will:
+ * 1. Extract parameter schema from the method signature
+ * 2. Present a configuration UI during install/setup
+ * 3. Store config at ~/.photon/{photonName}/config.json
+ * 4. Make config available via getConfig()
+ *
+ * Example:
+ * ```typescript
+ * export default class MyPhoton extends PhotonMCP {
+ *   async configure(params: {
+ *     apiEndpoint: string;
+ *     maxRetries?: number;
+ *   }) {
+ *     // Save config - framework handles storage
+ *     return { success: true };
+ *   }
+ *
+ *   async getConfig() {
+ *     // Read config - framework handles loading
+ *     return loadPhotonConfig('my-photon');
+ *   }
+ * }
+ * ```
+ */
+export interface ConfigSchema {
+  /** Whether configure() method exists */
+  hasConfigureMethod: boolean;
+  /** Whether getConfig() method exists */
+  hasGetConfigMethod: boolean;
+  /** Configuration parameters from configure() signature */
+  params: ConfigParam[];
+  /** Description from configure() JSDoc */
+  description?: string;
+}