@portel/photon 1.4.0 → 1.5.1

package/dist/shared/performance.js

@@ -0,0 +1,136 @@
+/**
+ * Performance monitoring utilities
+ * Provides timing, metrics collection, and performance insights
+ */
+export class PerformanceMonitor {
+    timings = new Map();
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Start timing an operation
+     */
+    start(name, metadata) {
+        this.timings.set(name, {
+            name,
+            startTime: Date.now(),
+            metadata,
+        });
+    }
+    /**
+     * End timing an operation and return duration
+     */
+    end(name) {
+        const metric = this.timings.get(name);
+        if (!metric) {
+            this.logger?.warn(`No timing found for: ${name}`);
+            return undefined;
+        }
+        const duration = Date.now() - metric.startTime;
+        metric.duration = duration;
+        this.logger?.debug(`⏱️  ${name}: ${duration}ms`, metric.metadata);
+        return duration;
+    }
+    /**
+     * Measure a synchronous function
+     */
+    measure(name, fn, metadata) {
+        this.start(name, metadata);
+        try {
+            const result = fn();
+            return result;
+        }
+        finally {
+            this.end(name);
+        }
+    }
+    /**
+     * Measure an async function
+     */
+    async measureAsync(name, fn, metadata) {
+        this.start(name, metadata);
+        try {
+            const result = await fn();
+            return result;
+        }
+        finally {
+            this.end(name);
+        }
+    }
+    /**
+     * Get all timings
+     */
+    getTimings() {
+        return Array.from(this.timings.values()).filter((m) => m.duration !== undefined);
+    }
+    /**
+     * Get summary statistics
+     */
+    getSummary() {
+        const completed = this.getTimings();
+        const total = completed.reduce((sum, m) => sum + (m.duration ?? 0), 0);
+        const count = completed.length;
+        const average = count > 0 ? total / count : 0;
+        const slowest = completed.reduce((max, m) => (!max || (m.duration ?? 0) > (max.duration ?? 0) ? m : max), undefined);
+        return { total, count, average, slowest };
+    }
+    /**
+     * Clear all timings
+     */
+    clear() {
+        this.timings.clear();
+    }
+}
+/**
+ * Simple memoization decorator for functions
+ */
+export function memoize(fn, options = {}) {
+    const cache = new Map();
+    const { ttl = Infinity, maxSize = 100 } = options;
+    return ((...args) => {
+        const key = JSON.stringify(args);
+        const cached = cache.get(key);
+        if (cached && Date.now() - cached.timestamp < ttl) {
+            return cached.value;
+        }
+        const value = fn(...args);
+        // Evict oldest if at capacity
+        if (cache.size >= maxSize) {
+            const firstKey = cache.keys().next().value;
+            if (firstKey !== undefined) {
+                cache.delete(firstKey);
+            }
+        }
+        cache.set(key, { value, timestamp: Date.now() });
+        return value;
+    });
+}
+/**
+ * Debounce a function
+ */
+export function debounce(fn, delayMs) {
+    let timeoutId = null;
+    return (...args) => {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+        timeoutId = setTimeout(() => {
+            fn(...args);
+        }, delayMs);
+    };
+}
+/**
+ * Throttle a function
+ */
+export function throttle(fn, delayMs) {
+    let lastCall = 0;
+    return (...args) => {
+        const now = Date.now();
+        if (now - lastCall >= delayMs) {
+            lastCall = now;
+            fn(...args);
+        }
+    };
+}
+//# sourceMappingURL=performance.js.map

package/dist/shared/performance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance.js","sourceRoot":"","sources":["../../src/shared/performance.ts"],"names":[],"mappings":"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"}

package/dist/shared/task-runner.d.ts

@@ -0,0 +1,2 @@
+export declare function runTask<T>(label: string, task: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=task-runner.d.ts.map

package/dist/shared/task-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-runner.d.ts","sourceRoot":"","sources":["../../src/shared/task-runner.ts"],"names":[],"mappings":"AAEA,wBAAsB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAYlF"}

package/dist/shared/task-runner.js

@@ -0,0 +1,16 @@
+import { performance } from 'node:perf_hooks';
+export async function runTask(label, task) {
+    const start = performance.now();
+    process.stdout.write(`▸ ${label}...`);
+    try {
+        const result = await task();
+        const duration = ((performance.now() - start) / 1000).toFixed(1);
+        process.stdout.write(`\r✔ ${label} (${duration}s)\n`);
+        return result;
+    }
+    catch (error) {
+        process.stdout.write(`\r✖ ${label}\n`);
+        throw error;
+    }
+}
+//# sourceMappingURL=task-runner.js.map

package/dist/shared/task-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-runner.js","sourceRoot":"","sources":["../../src/shared/task-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,MAAM,CAAC,KAAK,UAAU,OAAO,CAAI,KAAa,EAAE,IAAsB;IACpE,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAChC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;IACtC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAI,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,KAAK,KAAK,QAAQ,MAAM,CAAC,CAAC;QACtD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC;QACvC,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/shared/validation.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Input validation utilities
+ * Re-exported from @portel/photon-core
+ */
+export { 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 '@portel/photon-core';
+//# sourceMappingURL=validation.d.ts.map

package/dist/shared/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/shared/validation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,cAAc,EACd,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,SAAS,EACT,cAAc,EACd,OAAO,EACP,KAAK,EACL,OAAO,EACP,UAAU,EACV,SAAS,EACT,cAAc,EACd,OAAO,EACP,SAAS,EACT,KAAK,EACL,QAAQ,EACR,eAAe,EACf,UAAU,EACV,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,GACZ,MAAM,qBAAqB,CAAC"}

package/dist/shared/validation.js

@@ -0,0 +1,6 @@
+/**
+ * Input validation utilities
+ * Re-exported from @portel/photon-core
+ */
+export { 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 '@portel/photon-core';
+//# sourceMappingURL=validation.js.map

package/dist/shared/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/shared/validation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAGL,cAAc,EACd,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,SAAS,EACT,cAAc,EACd,OAAO,EACP,KAAK,EACL,OAAO,EACP,UAAU,EACV,SAAS,EACT,cAAc,EACd,OAAO,EACP,SAAS,EACT,KAAK,EACL,QAAQ,EACR,eAAe,EACf,UAAU,EACV,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,GACZ,MAAM,qBAAqB,CAAC"}

package/dist/shared-utils.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared utilities for Photon
+ *
+ * Centralized utility functions to eliminate code duplication
+ * across cli.ts, beam.ts, and photon-cli-runner.ts.
+ */
+/**
+ * Default bundled photons that ship with the runtime
+ */
+export declare const DEFAULT_BUNDLED_PHOTONS: string[];
+/**
+ * Extended bundled photons for beam (includes tunnel)
+ */
+export declare const BEAM_BUNDLED_PHOTONS: string[];
+/**
+ * Get path to a bundled photon (ships with runtime)
+ *
+ * @param name - Photon name (without .photon.ts extension)
+ * @param callerDir - __dirname of the calling module (used to resolve relative paths)
+ * @param bundledList - List of bundled photon names to check against
+ * @returns Absolute path to photon file, or null if not found
+ *
+ * @example
+ * ```typescript
+ * // From cli.ts (dist/cli.js)
+ * const photonPath = getBundledPhotonPath('maker', __dirname);
+ *
+ * // From beam.ts (dist/auto-ui/beam.js)
+ * const photonPath = getBundledPhotonPath('tunnel', __dirname, BEAM_BUNDLED_PHOTONS);
+ * ```
+ */
+export declare function getBundledPhotonPath(name: string, callerDir: string, bundledList?: string[]): string | null;
+/**
+ * Safely extract error message from unknown error type
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Execute an async operation with error context wrapping
+ *
+ * @param operation - Async function to execute
+ * @param context - Context string for error messages
+ * @param logger - Optional logger for error output
+ * @returns Result of operation
+ * @throws Wrapped error with context
+ *
+ * @example
+ * ```typescript
+ * const result = await withErrorContext(
+ *   () => loader.loadFile(photonPath),
+ *   `Loading photon: ${photonPath}`
+ * );
+ * ```
+ */
+export declare function withErrorContext<T>(operation: () => Promise<T>, context: string, logger?: {
+    error: (msg: string) => void;
+}): Promise<T>;
+/**
+ * Synchronous version of withErrorContext
+ */
+export declare function withErrorContextSync<T>(operation: () => T, context: string, logger?: {
+    error: (msg: string) => void;
+}): T;
+//# sourceMappingURL=shared-utils.d.ts.map

package/dist/shared-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-utils.d.ts","sourceRoot":"","sources":["../src/shared-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH;;GAEG;AACH,eAAO,MAAM,uBAAuB,UAAY,CAAC;AAEjD;;GAEG;AACH,eAAO,MAAM,oBAAoB,UAAqC,CAAC;AAEvE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,WAAW,GAAE,MAAM,EAA4B,GAC9C,MAAM,GAAG,IAAI,CA8Bf;AAMD;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQtD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE;IAAE,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACxC,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,SAAS,EAAE,MAAM,CAAC,EAClB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE;IAAE,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACxC,CAAC,CAUH"}

package/dist/shared-utils.js

@@ -0,0 +1,123 @@
+/**
+ * Shared utilities for Photon
+ *
+ * Centralized utility functions to eliminate code duplication
+ * across cli.ts, beam.ts, and photon-cli-runner.ts.
+ */
+import { existsSync } from 'fs';
+import * as path from 'path';
+// ════════════════════════════════════════════════════════════════════════════════
+// BUNDLED PHOTON RESOLUTION
+// ════════════════════════════════════════════════════════════════════════════════
+/**
+ * Default bundled photons that ship with the runtime
+ */
+export const DEFAULT_BUNDLED_PHOTONS = ['maker'];
+/**
+ * Extended bundled photons for beam (includes tunnel)
+ */
+export const BEAM_BUNDLED_PHOTONS = ['maker', 'marketplace', 'tunnel'];
+/**
+ * Get path to a bundled photon (ships with runtime)
+ *
+ * @param name - Photon name (without .photon.ts extension)
+ * @param callerDir - __dirname of the calling module (used to resolve relative paths)
+ * @param bundledList - List of bundled photon names to check against
+ * @returns Absolute path to photon file, or null if not found
+ *
+ * @example
+ * ```typescript
+ * // From cli.ts (dist/cli.js)
+ * const photonPath = getBundledPhotonPath('maker', __dirname);
+ *
+ * // From beam.ts (dist/auto-ui/beam.js)
+ * const photonPath = getBundledPhotonPath('tunnel', __dirname, BEAM_BUNDLED_PHOTONS);
+ * ```
+ */
+export function getBundledPhotonPath(name, callerDir, bundledList = DEFAULT_BUNDLED_PHOTONS) {
+    if (!bundledList.includes(name)) {
+        return null;
+    }
+    const filename = `${name}.photon.ts`;
+    // Build list of potential paths based on different module locations
+    // The paths vary depending on whether we're running from:
+    // - dist/cli.js
+    // - dist/auto-ui/beam.js
+    // - src/ during development
+    const searchPaths = [
+        // Standard dist layout: dist/photons/
+        path.join(callerDir, 'photons', filename),
+        // Dev layout from dist: ../src/photons/
+        path.join(callerDir, '..', 'src', 'photons', filename),
+        // Nested dist (auto-ui): ../photons/
+        path.join(callerDir, '..', 'photons', filename),
+        // Deep nested dev: ../../src/photons/
+        path.join(callerDir, '..', '..', 'src', 'photons', filename),
+    ];
+    for (const searchPath of searchPaths) {
+        if (existsSync(searchPath)) {
+            return searchPath;
+        }
+    }
+    return null;
+}
+// ════════════════════════════════════════════════════════════════════════════════
+// ERROR HANDLING UTILITIES
+// ════════════════════════════════════════════════════════════════════════════════
+/**
+ * Safely extract error message from unknown error type
+ */
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    return String(error);
+}
+/**
+ * Execute an async operation with error context wrapping
+ *
+ * @param operation - Async function to execute
+ * @param context - Context string for error messages
+ * @param logger - Optional logger for error output
+ * @returns Result of operation
+ * @throws Wrapped error with context
+ *
+ * @example
+ * ```typescript
+ * const result = await withErrorContext(
+ *   () => loader.loadFile(photonPath),
+ *   `Loading photon: ${photonPath}`
+ * );
+ * ```
+ */
+export async function withErrorContext(operation, context, logger) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        const message = `${context}: ${getErrorMessage(error)}`;
+        if (logger) {
+            logger.error(message);
+        }
+        throw new Error(message);
+    }
+}
+/**
+ * Synchronous version of withErrorContext
+ */
+export function withErrorContextSync(operation, context, logger) {
+    try {
+        return operation();
+    }
+    catch (error) {
+        const message = `${context}: ${getErrorMessage(error)}`;
+        if (logger) {
+            logger.error(message);
+        }
+        throw new Error(message);
+    }
+}
+//# sourceMappingURL=shared-utils.js.map

package/dist/shared-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-utils.js","sourceRoot":"","sources":["../src/shared-utils.ts"],"names":[],"mappings":"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"}

package/dist/template-manager.d.ts

@@ -24,10 +24,31 @@ export declare class TemplateManager {
      */
     renderTemplate(templateName: string, data: any): Promise<string>;
     /**
-     * Simple template renderer using template literals
-     * Safely evaluates ${expression} in templates
+     * Template renderer using a char-by-char walker.
+     *
+     * The template uses \` for escaped backticks, \$ to prevent interpolation,
+     * and \\\\ for literal backslashes. Expressions inside ${...} are extracted,
+     * globally unescaped (one level of \ removal), and evaluated as plain JS.
      */
     private render;
+    /**
+     * Walk template char by char, resolving escapes in text and evaluating
+     * ${...} expressions. Text escapes: \` → `, \$ → $, \\\\ → \\.
+     */
+    private evaluateTemplate;
+    /**
+     * Evaluate a JS expression extracted from the template.
+     * Expressions should be valid JS as-is (template literal delimiters are
+     * raw backticks, escaped backticks are \`, interpolations are ${...}).
+     */
+    private evalExpression;
+    /**
+     * Find the matching closing brace for a ${...} expression,
+     * correctly handling nested braces, strings, and template literals.
+     */
+    private findMatchingBrace;
+    private skipString;
+    private skipTemplateLiteral;
     /**
      * Ensure a single template exists and is up-to-date
      */

package/dist/template-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template-manager.d.ts","sourceRoot":"","sources":["../src/template-manager.ts"],"names":[],"mappings":"AAeA;;;;;GAKG;AACH,qBAAa,eAAe;IAQd,OAAO,CAAC,UAAU;IAP9B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAS;IAGzB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAW;gBAE/B,UAAU,EAAE,MAAM;IAMtC;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAetC;;OAEG;IACG,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKlE;;OAEG;IACG,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC;IAWtE;;;OAGG;IACH,OAAO,CAAC,MAAM;IAqDd;;OAEG;YACW,cAAc;IAqD5B;;OAEG;YACW,UAAU;IAaxB;;OAEG;YACW,UAAU;IAQxB;;OAEG;IACH,OAAO,CAAC,aAAa;IAIrB;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAqQhC;;OAEG;IACH,OAAO,CAAC,wBAAwB;CAsHjC"}
+{"version":3,"file":"template-manager.d.ts","sourceRoot":"","sources":["../src/template-manager.ts"],"names":[],"mappings":"AAgBA;;;;;GAKG;AACH,qBAAa,eAAe;IAQd,OAAO,CAAC,UAAU;IAP9B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAS;IAGzB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAW;gBAE/B,UAAU,EAAE,MAAM;IAMtC;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAetC;;OAEG;IACG,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKlE;;OAEG;IACG,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC;IAWtE;;;;;;OAMG;IACH,OAAO,CAAC,MAAM;IAiCd;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IA8CxB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAWtB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IA6BzB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,mBAAmB;IAgB3B;;OAEG;YACW,cAAc;IAqD5B;;OAEG;YACW,UAAU;IAaxB;;OAEG;YACW,UAAU;IAIxB;;OAEG;IACH,OAAO,CAAC,aAAa;IAIrB;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAqQhC;;OAEG;IACH,OAAO,CAAC,wBAAwB;CAsFjC"}