@portel/photon-core 2.3.0 → 2.4.0

package/src/asset-discovery.ts

@@ -0,0 +1,160 @@
+/**
+ * Asset Discovery Utilities
+ *
+ * Discover and extract UI, prompt, and resource assets from Photon files.
+ * Extracted from photon's loader.ts.
+ *
+ * Depends on: getMimeType (from ./mime-types), SchemaExtractor (from ./schema-extractor)
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { getMimeType } from './mime-types.js';
+import { SchemaExtractor } from './schema-extractor.js';
+import type { PhotonAssets } from './types.js';
+
+/**
+ * Check if a file or directory exists
+ */
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Discover and extract assets from a Photon file
+ *
+ * Convention:
+ * - Asset folder: {photon-name}/ next to {photon-name}.photon.ts
+ * - Subfolder: ui/, prompts/, resources/
+ *
+ * @param photonPath - Absolute path to the .photon.ts file
+ * @param source - Source code content of the Photon file
+ */
+export async function discoverAssets(
+  photonPath: string,
+  source: string,
+): Promise<PhotonAssets | undefined> {
+  const extractor = new SchemaExtractor();
+  const dir = path.dirname(photonPath);
+  const basename = path.basename(photonPath, '.photon.ts');
+
+  // Convention: asset folder has same name as photon (without .photon.ts)
+  const assetFolder = path.join(dir, basename);
+
+  // Check if asset folder exists
+  let folderExists = false;
+  try {
+    const stat = await fs.stat(assetFolder);
+    folderExists = stat.isDirectory();
+  } catch {
+    // Folder doesn't exist
+  }
+
+  // Extract explicit asset declarations from source annotations
+  const assets = extractor.extractAssets(source, folderExists ? assetFolder : undefined);
+
+  // If no folder exists and no explicit declarations, skip
+  if (
+    !folderExists &&
+    assets.ui.length === 0 &&
+    assets.prompts.length === 0 &&
+    assets.resources.length === 0
+  ) {
+    return undefined;
+  }
+
+  if (folderExists) {
+    // Resolve paths for explicitly declared assets
+    for (const ui of assets.ui) {
+      ui.resolvedPath = path.resolve(assetFolder, ui.path.replace(/^\.\//, ''));
+    }
+    for (const prompt of assets.prompts) {
+      prompt.resolvedPath = path.resolve(assetFolder, prompt.path.replace(/^\.\//, ''));
+    }
+    for (const resource of assets.resources) {
+      resource.resolvedPath = path.resolve(assetFolder, resource.path.replace(/^\.\//, ''));
+    }
+
+    // Auto-discover assets from folder structure
+    await autoDiscoverAssets(assetFolder, assets);
+  }
+
+  return assets;
+}
+
+/**
+ * Auto-discover assets from the ui/, prompts/, resources/ subdirectories
+ */
+export async function autoDiscoverAssets(
+  assetFolder: string,
+  assets: PhotonAssets,
+): Promise<void> {
+  // Auto-discover UI files
+  const uiDir = path.join(assetFolder, 'ui');
+  if (await fileExists(uiDir)) {
+    try {
+      const files = await fs.readdir(uiDir);
+      for (const file of files) {
+        const id = path.basename(file, path.extname(file));
+        if (!assets.ui.find((u) => u.id === id)) {
+          assets.ui.push({
+            id,
+            path: `./ui/${file}`,
+            resolvedPath: path.join(uiDir, file),
+            mimeType: getMimeType(file),
+          });
+        }
+      }
+    } catch {
+      // Ignore errors
+    }
+  }
+
+  // Auto-discover prompt files
+  const promptsDir = path.join(assetFolder, 'prompts');
+  if (await fileExists(promptsDir)) {
+    try {
+      const files = await fs.readdir(promptsDir);
+      for (const file of files) {
+        if (file.endsWith('.md') || file.endsWith('.txt')) {
+          const id = path.basename(file, path.extname(file));
+          if (!assets.prompts.find((p) => p.id === id)) {
+            assets.prompts.push({
+              id,
+              path: `./prompts/${file}`,
+              resolvedPath: path.join(promptsDir, file),
+            });
+          }
+        }
+      }
+    } catch {
+      // Ignore errors
+    }
+  }
+
+  // Auto-discover resource files
+  const resourcesDir = path.join(assetFolder, 'resources');
+  if (await fileExists(resourcesDir)) {
+    try {
+      const files = await fs.readdir(resourcesDir);
+      for (const file of files) {
+        const id = path.basename(file, path.extname(file));
+        if (!assets.resources.find((r) => r.id === id)) {
+          assets.resources.push({
+            id,
+            path: `./resources/${file}`,
+            resolvedPath: path.join(resourcesDir, file),
+            mimeType: getMimeType(file),
+          });
+        }
+      }
+    } catch {
+      // Ignore errors
+    }
+  }
+}

package/src/class-detection.ts

@@ -0,0 +1,94 @@
+/**
+ * Class Detection Utilities
+ *
+ * Shared logic for detecting Photon classes in ES modules.
+ * Extracted from photon, ncp, and lumina loaders.
+ */
+
+/**
+ * Check if a value is a class constructor
+ */
+export function isClass(fn: unknown): fn is new (...args: unknown[]) => unknown {
+  return typeof fn === 'function' && /^\s*class\s+/.test(fn.toString());
+}
+
+/**
+ * Check if a class has async methods (instance or static)
+ *
+ * Checks for AsyncFunction, AsyncGeneratorFunction, and GeneratorFunction
+ * on both prototype (instance methods) and the class itself (static methods).
+ */
+export function hasAsyncMethods(ClassConstructor: new (...args: unknown[]) => unknown): boolean {
+  const asyncCtorNames = new Set([
+    'AsyncFunction',
+    'AsyncGeneratorFunction',
+    'GeneratorFunction',
+  ]);
+
+  // Check instance methods on prototype
+  const prototype = ClassConstructor.prototype;
+  for (const key of Object.getOwnPropertyNames(prototype)) {
+    if (key === 'constructor') continue;
+    const descriptor = Object.getOwnPropertyDescriptor(prototype, key);
+    if (descriptor && typeof descriptor.value === 'function') {
+      if (asyncCtorNames.has(descriptor.value.constructor.name)) {
+        return true;
+      }
+    }
+  }
+
+  // Check static methods on the class itself
+  for (const key of Object.getOwnPropertyNames(ClassConstructor)) {
+    if (['length', 'name', 'prototype'].includes(key)) continue;
+    const descriptor = Object.getOwnPropertyDescriptor(ClassConstructor, key);
+    if (descriptor && typeof descriptor.value === 'function') {
+      if (asyncCtorNames.has(descriptor.value.constructor.name)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Find a single Photon class in a module
+ *
+ * Priority: default export first, then named exports.
+ * Returns the first class with async methods, or null.
+ */
+export function findPhotonClass(module: Record<string, unknown>): (new (...args: unknown[]) => unknown) | null {
+  // Try default export first
+  if (module.default && isClass(module.default)) {
+    if (hasAsyncMethods(module.default)) {
+      return module.default;
+    }
+  }
+
+  // Try named exports
+  for (const exportedItem of Object.values(module)) {
+    if (isClass(exportedItem) && hasAsyncMethods(exportedItem)) {
+      return exportedItem;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Find all Photon classes in a module
+ *
+ * Returns every exported class that has async methods.
+ * Used by NCP which may load multiple classes from one file.
+ */
+export function findPhotonClasses(module: Record<string, unknown>): Array<new (...args: unknown[]) => unknown> {
+  const classes: Array<new (...args: unknown[]) => unknown> = [];
+
+  for (const exportedItem of Object.values(module)) {
+    if (isClass(exportedItem) && hasAsyncMethods(exportedItem)) {
+      classes.push(exportedItem);
+    }
+  }
+
+  return classes;
+}

package/src/compiler.ts

@@ -0,0 +1,57 @@
+/**
+ * TypeScript Compiler Utilities
+ *
+ * Shared esbuild-based TypeScript compilation with caching.
+ * Extracted from photon and ncp loaders.
+ *
+ * NOTE: No esbuild dependency in package.json — the consumer must provide it.
+ * Uses `await import('esbuild')` for dynamic resolution.
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as crypto from 'crypto';
+
+/**
+ * Compile a .photon.ts file to JavaScript and cache the result
+ *
+ * @param tsFilePath - Absolute path to the TypeScript source file
+ * @param options.cacheDir - Directory to store compiled output
+ * @param options.content - Optional pre-read file content (avoids extra read)
+ * @returns Absolute path to the compiled .mjs file
+ */
+export async function compilePhotonTS(
+  tsFilePath: string,
+  options: { cacheDir: string; content?: string },
+): Promise<string> {
+  const source = options.content ?? (await fs.readFile(tsFilePath, 'utf-8'));
+  const hash = crypto.createHash('sha256').update(source).digest('hex').slice(0, 16);
+
+  const fileName = path.basename(tsFilePath, '.ts');
+  const cachedJsPath = path.join(options.cacheDir, `${fileName}.${hash}.mjs`);
+
+  // Check if cached version exists
+  try {
+    await fs.access(cachedJsPath);
+    return cachedJsPath;
+  } catch {
+    // Cache miss — compile
+  }
+
+  // Dynamic import — consumer must have esbuild installed
+  const esbuild = await import('esbuild');
+  const result = await esbuild.transform(source, {
+    loader: 'ts',
+    format: 'esm',
+    target: 'es2022',
+    sourcemap: 'inline',
+  });
+
+  // Ensure cache directory exists
+  await fs.mkdir(options.cacheDir, { recursive: true });
+
+  // Write compiled JavaScript
+  await fs.writeFile(cachedJsPath, result.code, 'utf-8');
+
+  return cachedJsPath;
+}

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,83 @@ 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';

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';
+}