@portel/photon-core 1.0.0 → 1.0.2

package/src/path-resolver.ts

@@ -0,0 +1,120 @@
+/**
+ * Path Resolver for Photon files
+ *
+ * Generic path resolution utilities used by photon, lumina, ncp.
+ * Configurable file extensions and default directories.
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+
+export const DEFAULT_PHOTON_DIR = path.join(os.homedir(), '.photon');
+
+export interface ResolverOptions {
+  /** File extensions to look for (default: ['.photon.ts', '.photon.js']) */
+  extensions?: string[];
+  /** Default working directory */
+  defaultDir?: string;
+}
+
+const defaultOptions: Required<ResolverOptions> = {
+  extensions: ['.photon.ts', '.photon.js'],
+  defaultDir: DEFAULT_PHOTON_DIR,
+};
+
+/**
+ * Resolve a file path from name
+ * Looks in the specified working directory, or uses absolute path if provided
+ */
+export async function resolvePath(
+  name: string,
+  workingDir?: string,
+  options?: ResolverOptions
+): Promise<string | null> {
+  const opts = { ...defaultOptions, ...options };
+  const dir = workingDir || opts.defaultDir;
+
+  // If absolute path provided, check if it exists
+  if (path.isAbsolute(name)) {
+    try {
+      await fs.access(name);
+      return name;
+    } catch {
+      return null;
+    }
+  }
+
+  // Remove extension if provided (match any configured extension)
+  let basename = name;
+  for (const ext of opts.extensions) {
+    if (name.endsWith(ext)) {
+      basename = name.slice(0, -ext.length);
+      break;
+    }
+  }
+
+  // Try each extension
+  for (const ext of opts.extensions) {
+    const filePath = path.join(dir, `${basename}${ext}`);
+    try {
+      await fs.access(filePath);
+      return filePath;
+    } catch {
+      // Continue to next extension
+    }
+  }
+
+  // Not found
+  return null;
+}
+
+/**
+ * List all matching files in a directory
+ */
+export async function listFiles(
+  workingDir?: string,
+  options?: ResolverOptions
+): Promise<string[]> {
+  const opts = { ...defaultOptions, ...options };
+  const dir = workingDir || opts.defaultDir;
+
+  try {
+    // Ensure directory exists
+    await fs.mkdir(dir, { recursive: true });
+
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const files: string[] = [];
+
+    for (const entry of entries) {
+      if (entry.isFile()) {
+        // Check if file matches any extension
+        for (const ext of opts.extensions) {
+          if (entry.name.endsWith(ext)) {
+            // Remove extension for display
+            const name = entry.name.slice(0, -ext.length);
+            files.push(name);
+            break;
+          }
+        }
+      }
+    }
+
+    return files.sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Ensure directory exists
+ */
+export async function ensureDir(dir?: string): Promise<void> {
+  const targetDir = dir || DEFAULT_PHOTON_DIR;
+  await fs.mkdir(targetDir, { recursive: true });
+}
+
+// Convenience aliases for photon-specific usage
+export const resolvePhotonPath = resolvePath;
+export const listPhotonFiles = listFiles;
+export const ensurePhotonDir = ensureDir;

package/src/schema-extractor.ts

@@ -10,7 +10,7 @@
 
 import * as fs from 'fs/promises';
 import * as ts from 'typescript';
-import { ExtractedSchema, ConstructorParam, TemplateInfo, StaticInfo } from './types.js';
+import { ExtractedSchema, ConstructorParam, TemplateInfo, StaticInfo, OutputFormat } from './types.js';
 
 export interface ExtractedMetadata {
   tools: ExtractedSchema[];
@@ -125,12 +125,12 @@ export class SchemaExtractor {
         }
         // Otherwise, it's a regular tool
         else {
-          const format = this.extractFormat(jsdoc);
+          const outputFormat = this.extractFormat(jsdoc);
           tools.push({
             name: methodName,
             description,
             inputSchema,
-            ...(format ? { format } : {}),
+            ...(outputFormat ? { outputFormat } : {}),
           });
         }
       };
@@ -813,12 +813,28 @@ export class SchemaExtractor {
   /**
    * Extract format hint from @format tag
    * Example: @format table
+   * Example: @format json
+   * Example: @format code:typescript
    */
-  private extractFormat(jsdocContent: string): 'primitive' | 'table' | 'tree' | 'list' | 'none' | undefined {
-    const match = jsdocContent.match(/@format\s+(primitive|table|tree|list|none)/i);
-    if (match) {
-      return match[1].toLowerCase() as 'primitive' | 'table' | 'tree' | 'list' | 'none';
+  private extractFormat(jsdocContent: string): OutputFormat | undefined {
+    // Match structural formats
+    const structuralMatch = jsdocContent.match(/@format\s+(primitive|table|tree|list|none)/i);
+    if (structuralMatch) {
+      return structuralMatch[1].toLowerCase() as OutputFormat;
     }
+
+    // Match content formats
+    const contentMatch = jsdocContent.match(/@format\s+(json|markdown|yaml|xml|html)/i);
+    if (contentMatch) {
+      return contentMatch[1].toLowerCase() as OutputFormat;
+    }
+
+    // Match code format (with optional language)
+    const codeMatch = jsdocContent.match(/@format\s+code(?::(\w+))?/i);
+    if (codeMatch) {
+      return codeMatch[1] ? `code:${codeMatch[1]}` as OutputFormat : 'code';
+    }
+
     return undefined;
   }
 

package/src/types.ts

@@ -2,6 +2,16 @@
  * Photon MCP Core Types
  */
 
+/**
+ * Output format types
+ * - Structural: primitive, table, tree, list, none
+ * - Content: json, markdown, yaml, xml, html, code, code:<lang>
+ */
+export type OutputFormat =
+  | 'primitive' | 'table' | 'tree' | 'list' | 'none'
+  | 'json' | 'markdown' | 'yaml' | 'xml' | 'html'
+  | `code` | `code:${string}`;
+
 export interface PhotonTool {
   name: string;
   description: string;
@@ -10,6 +20,7 @@ export interface PhotonTool {
     properties: Record<string, any>;
     required?: string[];
   };
+  outputFormat?: OutputFormat;
 }
 
 export interface ExtractedSchema {
@@ -20,7 +31,7 @@ export interface ExtractedSchema {
     properties: Record<string, any>;
     required?: string[];
   };
-  format?: 'primitive' | 'table' | 'tree' | 'list' | 'none';
+  outputFormat?: OutputFormat;
 }
 
 export interface PhotonMCPClass {