@portel/photon-core 2.3.0 → 2.5.0

package/src/env-utils.ts

@@ -0,0 +1,216 @@
+/**
+ * Environment Variable Utilities
+ *
+ * Shared logic for resolving constructor parameters from environment variables.
+ * Extracted from photon's config-docs.ts and lumina's photon-loader.ts.
+ */
+
+/**
+ * Minimal constructor parameter info needed for env resolution.
+ * Compatible with both photon-core's full ConstructorParam and
+ * lumina's simplified version (which omits isPrimitive).
+ */
+export interface EnvConstructorParam {
+  name: string;
+  type: string;
+  isOptional: boolean;
+  hasDefault: boolean;
+  defaultValue?: any;
+}
+
+/**
+ * Info about a missing required parameter
+ */
+export interface MissingParamInfo {
+  paramName: string;
+  envVarName: string;
+  type: string;
+}
+
+/**
+ * Convert a photon name and parameter name to an environment variable name
+ *
+ * @example toEnvVarName('my-mcp', 'apiKey') → 'MY_MCP_API_KEY'
+ */
+export function toEnvVarName(photonName: string, paramName: string): string {
+  const prefix = photonName.toUpperCase().replace(/-/g, '_');
+  const suffix = paramName
+    .replace(/([A-Z])/g, '_$1')
+    .toUpperCase()
+    .replace(/^_/, '');
+  return `${prefix}_${suffix}`;
+}
+
+/**
+ * Parse an environment variable string value to the appropriate type
+ */
+export function parseEnvValue(value: string, type: string): any {
+  switch (type) {
+    case 'number':
+      return parseFloat(value);
+    case 'boolean':
+      return value.toLowerCase() === 'true';
+    case 'string':
+    default:
+      return value;
+  }
+}
+
+/**
+ * Generate a sensible example value for a parameter based on its name and type
+ */
+export function generateExampleValue(paramName: string, paramType: string): string | null {
+  const lowerName = paramName.toLowerCase();
+
+  if (lowerName.includes('apikey') || lowerName.includes('api_key')) {
+    return 'sk_your_api_key_here';
+  }
+  if (lowerName.includes('token') || lowerName.includes('secret')) {
+    return 'your_secret_token';
+  }
+  if (lowerName.includes('url') || lowerName.includes('endpoint')) {
+    return 'https://api.example.com';
+  }
+  if (lowerName.includes('host') || lowerName.includes('server')) {
+    return 'localhost';
+  }
+  if (lowerName.includes('port')) {
+    return '5432';
+  }
+  if (lowerName.includes('database') || lowerName.includes('db')) {
+    return 'my_database';
+  }
+  if (lowerName.includes('user') || lowerName.includes('username')) {
+    return 'admin';
+  }
+  if (lowerName.includes('password')) {
+    return 'your_secure_password';
+  }
+  if (lowerName.includes('path') || lowerName.includes('dir')) {
+    return '/path/to/directory';
+  }
+  if (lowerName.includes('name')) {
+    return 'my-service';
+  }
+  if (lowerName.includes('region')) {
+    return 'us-east-1';
+  }
+  if (paramType === 'boolean') {
+    return 'true';
+  }
+  if (paramType === 'number') {
+    return '3000';
+  }
+
+  return null;
+}
+
+/**
+ * Generate documentation and example env vars for constructor parameters
+ */
+export function summarizeConstructorParams(
+  params: EnvConstructorParam[],
+  photonName: string,
+): { docs: string; exampleEnv: Record<string, string> } {
+  const docs = params
+    .map((param) => {
+      const envVarName = toEnvVarName(photonName, param.name);
+      const required = !param.isOptional && !param.hasDefault;
+      const status = required ? '[REQUIRED]' : '[OPTIONAL]';
+      const defaultInfo = param.hasDefault
+        ? ` (default: ${JSON.stringify(param.defaultValue)})`
+        : '';
+      const exampleValue = generateExampleValue(param.name, param.type);
+
+      let line = `  • ${envVarName} ${status}`;
+      line += `\n    Type: ${param.type}${defaultInfo}`;
+      if (exampleValue) {
+        line += `\n    Example: ${envVarName}="${exampleValue}"`;
+      }
+      return line;
+    })
+    .join('\n\n');
+
+  const exampleEnv: Record<string, string> = {};
+  params.forEach((param) => {
+    const envVarName = toEnvVarName(photonName, param.name);
+    if (!param.isOptional && !param.hasDefault) {
+      exampleEnv[envVarName] =
+        generateExampleValue(param.name, param.type) || `your-${param.name}`;
+    }
+  });
+
+  return { docs, exampleEnv };
+}
+
+/**
+ * Generate a user-friendly error message for missing configuration
+ */
+export function generateConfigErrorMessage(
+  photonName: string,
+  missing: MissingParamInfo[],
+): string {
+  const envVarList = missing
+    .map((m) => `  • ${m.envVarName} (${m.paramName}: ${m.type})`)
+    .join('\n');
+  const exampleEnv = Object.fromEntries(
+    missing.map((m) => [m.envVarName, `<your-${m.paramName}>`]),
+  );
+
+  return `
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️  Configuration Warning: ${photonName} MCP
+
+Missing required environment variables:
+${envVarList}
+
+Tools will fail until configuration is fixed.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+To fix, add environment variables to your MCP client config:
+
+{
+  "mcpServers": {
+    "${photonName}": {
+      "command": "npx",
+      "args": ["@portel/photon", "${photonName}"],
+      "env": ${JSON.stringify(exampleEnv, null, 8).replace(/\n/g, '\n      ')}
+    }
+  }
+}
+
+Or run: photon ${photonName} --config
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`.trim();
+}
+
+/**
+ * Resolve constructor arguments from environment variables
+ *
+ * @returns values array (aligned with params) and configError string if any required params are missing
+ */
+export function resolveEnvArgs(
+  params: EnvConstructorParam[],
+  photonName: string,
+): { values: any[]; missing: MissingParamInfo[] } {
+  const values: any[] = [];
+  const missing: MissingParamInfo[] = [];
+
+  for (const param of params) {
+    const envVarName = toEnvVarName(photonName, param.name);
+    const envValue = process.env[envVarName];
+
+    if (envValue !== undefined) {
+      values.push(parseEnvValue(envValue, param.type));
+    } else if (param.hasDefault || param.isOptional) {
+      values.push(undefined);
+    } else {
+      missing.push({ paramName: param.name, envVarName, type: param.type });
+      values.push(undefined);
+    }
+  }
+
+  return { values, missing };
+}

package/src/index.ts

@@ -360,3 +360,158 @@ export {
   deletePhotonConfig,
   listConfiguredPhotons,
 } from './config.js';
+
+// ===== CLASS DETECTION =====
+// Shared Photon class detection for loaders
+export {
+  isClass,
+  hasAsyncMethods,
+  findPhotonClass,
+  findPhotonClasses,
+} from './class-detection.js';
+
+// ===== ENVIRONMENT UTILITIES =====
+// Env var resolution for constructor injection
+export {
+  toEnvVarName,
+  parseEnvValue,
+  generateExampleValue,
+  summarizeConstructorParams,
+  generateConfigErrorMessage,
+  resolveEnvArgs,
+  type MissingParamInfo,
+  type EnvConstructorParam,
+} from './env-utils.js';
+
+// ===== TYPESCRIPT COMPILER =====
+// esbuild-based .photon.ts compilation with caching
+export { compilePhotonTS } from './compiler.js';
+
+// ===== MIME TYPES =====
+// Extension-to-MIME mapping for assets
+export { getMimeType } from './mime-types.js';
+
+// ===== VERSION CHECK =====
+// @runtime tag parsing and semver-lite compatibility check
+export {
+  parseRuntimeRequirement,
+  checkRuntimeCompatibility,
+} from './version-check.js';
+
+// ===== VALIDATION =====
+// Input validation utilities and error base classes
+export {
+  PhotonError,
+  ValidationError,
+  type ValidationResult,
+  type Validator,
+  combineResults,
+  isString,
+  isNumber,
+  isBoolean,
+  isObject,
+  isArray,
+  notEmpty,
+  hasLength,
+  matchesPattern,
+  isEmail,
+  isUrl,
+  inRange,
+  isPositive,
+  isInteger,
+  hasArrayLength,
+  arrayOf,
+  hasFields,
+  oneOf,
+  validate,
+  validateOrThrow,
+  pathExists,
+  hasExtension,
+  assertDefined,
+  assertString,
+  assertNumber,
+  assertObject,
+  assertArray,
+} from './validation.js';
+
+// ===== ASSET DISCOVERY =====
+// Discover UI, prompt, and resource assets from Photon files
+export {
+  discoverAssets,
+  autoDiscoverAssets,
+} from './asset-discovery.js';
+
+// ===== MANAGED COLLECTIONS =====
+// Auto-emit events on mutations for seamless real-time sync
+export {
+  ReactiveArray,
+  ReactiveMap,
+  ReactiveSet,
+  type Emitter,
+} from './collections/index.js';
+
+// ===== PURPOSE-DRIVEN UI TYPES =====
+// Polymorphic return types that auto-render with appropriate UI
+export {
+  // Base
+  PhotonUIType,
+  isPhotonUIType,
+
+  // Field System (React Admin-style)
+  Field,
+  type FieldDefinition,
+  type FieldType,
+  type FieldAlignment,
+  type BaseFieldOptions,
+  type TextFieldOptions,
+  type NumberFieldOptions,
+  type CurrencyFieldOptions,
+  type DateFieldOptions,
+  type DateFormat,
+  type ImageFieldOptions,
+  type BadgeFieldOptions,
+  type RatingFieldOptions,
+  type PriceFieldOptions,
+  type StockFieldOptions,
+  type ActionItem,
+  type ActionsFieldOptions,
+  type RenderFunction,
+  getFieldValue,
+  formatFieldLabel,
+  interpolateTemplate,
+  renderFieldToText,
+  renderFieldToStructured,
+  type RenderedField,
+
+  // Data Display
+  Table,
+  type TableColumn,
+  type TableOptions,
+  type ColumnType,
+  Cards,
+  type CardFieldMapping,
+  type CardsOptions,
+
+  // Visualization
+  Chart,
+  type ChartType,
+  type ChartSeries,
+  type ChartDataPoint,
+  type ChartOptions,
+  Stats,
+  type StatItem,
+  type StatFormat,
+  type StatsOptions,
+  Progress,
+  type ProgressBar,
+  type ProgressStep,
+  type ProgressStyle,
+  type StepStatus,
+  type ProgressOptions,
+
+  // Interactive
+  Form,
+  type FormField,
+  type FieldType as FormFieldType,
+  type FormOptions,
+} from './ui-types/index.js';

package/src/mime-types.ts

@@ -0,0 +1,49 @@
+/**
+ * MIME Type Utilities
+ *
+ * Extension-to-MIME mapping for Photon assets.
+ * Extracted from photon's loader.ts.
+ */
+
+import * as path from 'path';
+
+const MIME_TYPES: Record<string, string> = {
+  html: 'text/html',
+  htm: 'text/html',
+  css: 'text/css',
+  js: 'application/javascript',
+  mjs: 'application/javascript',
+  jsx: 'text/jsx',
+  ts: 'text/typescript',
+  tsx: 'text/tsx',
+  json: 'application/json',
+  yaml: 'application/yaml',
+  yml: 'application/yaml',
+  xml: 'application/xml',
+  md: 'text/markdown',
+  txt: 'text/plain',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  svg: 'image/svg+xml',
+  webp: 'image/webp',
+  ico: 'image/x-icon',
+  woff: 'font/woff',
+  woff2: 'font/woff2',
+  ttf: 'font/ttf',
+  otf: 'font/otf',
+  pdf: 'application/pdf',
+  zip: 'application/zip',
+  csv: 'text/csv',
+};
+
+/**
+ * Get MIME type from a filename based on its extension
+ *
+ * @returns The MIME type string, or 'application/octet-stream' for unknown extensions
+ */
+export function getMimeType(filename: string): string {
+  const ext = path.extname(filename).toLowerCase().slice(1);
+  return MIME_TYPES[ext] || 'application/octet-stream';
+}

package/src/rendering/index.ts

@@ -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

@@ -184,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,
@@ -196,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 } : {}),

package/src/types.ts

@@ -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 ═══
 
@@ -371,6 +373,8 @@ export interface PhotonMCPClassExtended extends PhotonMCPClass {
   statics: StaticInfo[];
   /** Assets from the Photon's asset folder (UI, prompts, resources) */
   assets?: PhotonAssets;
+  /** Names of injected @photon dependencies (for client-side event routing) */
+  injectedPhotons?: string[];
 }
 
 // ══════════════════════════════════════════════════════════════════════════════