@portel/photon-core 2.17.6 → 2.18.0

package/src/audit.ts

@@ -19,9 +19,14 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
-import * as os from 'os';
 import * as crypto from 'crypto';
 
+import {
+  getPhotonLogsDir,
+  getLegacyLogsDir,
+  getDataRoot,
+} from './data-paths.js';
+
 /**
  * A single execution record
  */
@@ -73,19 +78,25 @@ export function generateExecutionId(): string {
 }
 
 /**
- * Get the logs directory for a photon
+ * Get the logs directory for a photon.
+ * New path: .data/{namespace}/{photonName}/logs/
+ * Falls back to legacy ~/.photon/logs/{photonId}/ for reads.
  */
-function getLogDir(photonId: string): string {
-  const safeName = photonId.replace(/[^a-zA-Z0-9_-]/g, '_');
-  const baseDir = process.env.PHOTON_LOG_DIR || path.join(os.homedir(), '.photon', 'logs');
-  return path.join(baseDir, safeName);
+function getLogDir(photonId: string, namespace?: string): string {
+  const ns = namespace || 'local';
+  const newDir = getPhotonLogsDir(ns, photonId);
+  if (!fs.existsSync(newDir)) {
+    const legacyDir = getLegacyLogsDir(photonId);
+    if (fs.existsSync(legacyDir)) return legacyDir;
+  }
+  return newDir;
 }
 
 /**
  * Get the executions log file path
  */
-function getLogPath(photonId: string): string {
-  return path.join(getLogDir(photonId), 'executions.jsonl');
+function getLogPath(photonId: string, namespace?: string): string {
+  return path.join(getLogDir(photonId, namespace), 'executions.jsonl');
 }
 
 /**
@@ -234,16 +245,9 @@ export class AuditTrail {
       return this.findInLog(getLogPath(photonId), executionId);
     }
 
-    // Otherwise, search all photon logs
-    const baseDir = process.env.PHOTON_LOG_DIR || path.join(os.homedir(), '.photon', 'logs');
-    if (!fs.existsSync(baseDir)) return null;
-
-    const dirs = fs.readdirSync(baseDir, { withFileTypes: true })
-      .filter(d => d.isDirectory())
-      .map(d => d.name);
-
-    for (const dir of dirs) {
-      const found = this.findInLog(path.join(baseDir, dir, 'executions.jsonl'), executionId);
+    // Search all photon logs across namespaces in .data/
+    for (const logPath of this.allLogPaths()) {
+      const found = this.findInLog(logPath, executionId);
       if (found) return found;
     }
 
@@ -260,17 +264,8 @@ export class AuditTrail {
     const result = [root];
 
     // Find all children across all photon logs
-    const baseDir = process.env.PHOTON_LOG_DIR || path.join(os.homedir(), '.photon', 'logs');
-    if (!fs.existsSync(baseDir)) return result;
-
-    const dirs = fs.readdirSync(baseDir, { withFileTypes: true })
-      .filter(d => d.isDirectory())
-      .map(d => d.name);
-
-    for (const dir of dirs) {
-      const logPath = path.join(baseDir, dir, 'executions.jsonl');
+    for (const logPath of this.allLogPaths()) {
       if (!fs.existsSync(logPath)) continue;
-
       const content = fs.readFileSync(logPath, 'utf-8');
       const lines = content.trim().split('\n').filter(Boolean);
 
@@ -294,13 +289,47 @@ export class AuditTrail {
    * List all photons that have execution logs
    */
   listPhotons(): string[] {
-    const baseDir = process.env.PHOTON_LOG_DIR || path.join(os.homedir(), '.photon', 'logs');
-    if (!fs.existsSync(baseDir)) return [];
+    const results: string[] = [];
+    const dataRoot = getDataRoot();
+    if (!fs.existsSync(dataRoot)) return results;
+
+    try {
+      // Scan .data/{ns}/{photon}/logs/executions.jsonl
+      const nsDirs = fs.readdirSync(dataRoot, { withFileTypes: true })
+        .filter(e => e.isDirectory() && !e.name.startsWith('_') && !e.name.startsWith('.'));
+
+      for (const nsDir of nsDirs) {
+        const nsPath = path.join(dataRoot, nsDir.name);
+        const photonDirs = fs.readdirSync(nsPath, { withFileTypes: true })
+          .filter(e => e.isDirectory());
+
+        for (const pDir of photonDirs) {
+          if (fs.existsSync(path.join(nsPath, pDir.name, 'logs', 'executions.jsonl'))) {
+            results.push(pDir.name);
+          }
+        }
+      }
+    } catch {
+      // Unreadable
+    }
 
-    return fs.readdirSync(baseDir, { withFileTypes: true })
-      .filter(d => d.isDirectory())
-      .filter(d => fs.existsSync(path.join(baseDir, d.name, 'executions.jsonl')))
-      .map(d => d.name);
+    // Also check legacy path
+    try {
+      const legacyDir = path.join(path.dirname(dataRoot), 'logs');
+      if (fs.existsSync(legacyDir)) {
+        const dirs = fs.readdirSync(legacyDir, { withFileTypes: true })
+          .filter(d => d.isDirectory())
+          .filter(d => fs.existsSync(path.join(legacyDir, d.name, 'executions.jsonl')))
+          .map(d => d.name);
+        for (const d of dirs) {
+          if (!results.includes(d)) results.push(d);
+        }
+      }
+    } catch {
+      // Legacy dir doesn't exist
+    }
+
+    return results;
   }
 
   /**
@@ -366,10 +395,12 @@ export class AuditTrail {
       return;
     }
 
-    // Clear all
-    const baseDir = process.env.PHOTON_LOG_DIR || path.join(os.homedir(), '.photon', 'logs');
-    if (fs.existsSync(baseDir)) {
-      fs.rmSync(baseDir, { recursive: true, force: true });
+    // Clear all — remove log dirs inside .data/{ns}/{photon}/logs/
+    for (const logPath of this.allLogPaths()) {
+      const logDir = path.dirname(logPath);
+      if (fs.existsSync(logDir)) {
+        fs.rmSync(logDir, { recursive: true, force: true });
+      }
     }
   }
 
@@ -402,6 +433,48 @@ export class AuditTrail {
     return output;
   }
 
+  /**
+   * Collect all executions.jsonl paths across namespaces
+   */
+  private allLogPaths(): string[] {
+    const paths: string[] = [];
+    const dataRoot = getDataRoot();
+
+    try {
+      if (fs.existsSync(dataRoot)) {
+        const nsDirs = fs.readdirSync(dataRoot, { withFileTypes: true })
+          .filter(e => e.isDirectory() && !e.name.startsWith('_') && !e.name.startsWith('.'));
+
+        for (const nsDir of nsDirs) {
+          const nsPath = path.join(dataRoot, nsDir.name);
+          try {
+            const photonDirs = fs.readdirSync(nsPath, { withFileTypes: true })
+              .filter(e => e.isDirectory());
+            for (const pDir of photonDirs) {
+              const logPath = path.join(nsPath, pDir.name, 'logs', 'executions.jsonl');
+              if (fs.existsSync(logPath)) paths.push(logPath);
+            }
+          } catch { /* skip unreadable ns dir */ }
+        }
+      }
+    } catch { /* data root doesn't exist */ }
+
+    // Also check legacy
+    try {
+      const legacyDir = path.join(path.dirname(dataRoot), 'logs');
+      if (fs.existsSync(legacyDir)) {
+        const dirs = fs.readdirSync(legacyDir, { withFileTypes: true })
+          .filter(d => d.isDirectory());
+        for (const d of dirs) {
+          const logPath = path.join(legacyDir, d.name, 'executions.jsonl');
+          if (fs.existsSync(logPath)) paths.push(logPath);
+        }
+      }
+    } catch { /* legacy doesn't exist */ }
+
+    return paths;
+  }
+
   /**
    * Find a record by ID in a specific log file
    */

package/src/base.ts

@@ -47,6 +47,7 @@ import { MemoryProvider } from './memory.js';
 import { ScheduleProvider } from './schedule.js';
 import * as path from 'path';
 import * as fs from 'fs';
+import { getPhotonDataDir } from './data-paths.js';
 
 /**
  * Simple base class for creating Photons
@@ -63,6 +64,13 @@ export class Photon {
    */
   _photonName?: string;
 
+  /**
+   * Photon namespace (marketplace owner) - set by runtime loader
+   * Used for data path resolution: .data/{namespace}/{name}/
+   * @internal
+   */
+  _photonNamespace?: string;
+
   /**
    * Absolute path to the .photon.ts/.photon.js source file - set by runtime loader
    * Used for storage() and assets() path resolution
@@ -145,7 +153,7 @@ export class Photon {
         .replace(/([A-Z])/g, '-$1')
         .toLowerCase()
         .replace(/^-/, '');
-      this._memory = new MemoryProvider(name, this._sessionId);
+      this._memory = new MemoryProvider(name, this._sessionId, this._photonNamespace);
     }
     return this._memory;
   }
@@ -219,9 +227,9 @@ export class Photon {
         'Ensure this photon is loaded through the standard runtime.'
       );
     }
-    const dir = path.dirname(this._photonFilePath);
-    const name = path.basename(this._photonFilePath).replace(/\.photon\.(ts|js)$/, '');
-    const target = path.join(dir, name, subpath);
+    const name = this._photonName || path.basename(this._photonFilePath).replace(/\.photon\.(ts|js)$/, '');
+    const ns = this._photonNamespace || 'local';
+    const target = path.join(getPhotonDataDir(ns, name), subpath);
     fs.mkdirSync(target, { recursive: true });
     return target;
   }
@@ -386,35 +394,125 @@ export class Photon {
    * format — the same formats available via `@format` docblock tags. Each call
    * replaces the previous render in the result panel.
    *
+   * Also supports UI feedback formats: status, progress, toast.
    * For custom formats, place an HTML renderer at `assets/formats/<name>.html`.
    *
-   * @param format The format type (table, qr, chart:bar, dashboard, or custom)
-   * @param value The data to render — same shape as a return value with that @format
+   * @param format The format type (table, qr, status, progress, toast, guide, or custom)
+   * @param value The data to render — shape depends on format
    *
    * @example
    * ```typescript
-   * // Show a QR code mid-execution
-   * this.render('qr', { value: 'https://wa.link/...' });
-   *
-   * // Show a status table
+   * // Status message
+   * this.render('status', 'Connecting...');
+   * this.render('status', { message: 'Error!', type: 'error' });
+   *
+   * // Progress bar (0–1)
+   * this.render('progress', 0.5);
+   * this.render('progress', { value: 0.75, message: 'Almost done' });
+   *
+   * // Toast notification
+   * this.render('toast', 'Saved!');
+   * this.render('toast', { message: 'Done!', type: 'success' });
+   *
+   * // Multi-step guide
+   * this.render('guide', [
+   *   { label: 'Create bot', status: 'done' },
+   *   { label: 'Enter token', status: 'active' },
+   *   { label: 'Connect', status: 'pending' },
+   * ]);
+   *
+   * // Formatted data
    * this.render('table', [['Step', 'Status'], ['Auth', 'Done']]);
-   *
-   * // Composite dashboard
-   * this.render('dashboard', {
-   *   qr: { format: 'qr', data: 'https://wa.link/...' },
-   *   status: { format: 'text', data: 'Scan the QR code above' }
-   * });
+   * this.render('qr', { value: 'https://wa.link/...' });
    * ```
    */
   protected render(format: string, value: any): void;
   protected render(): void;
   protected render(format?: string, value?: any): void {
     if (format === undefined) {
-      // Clear the render zone without rendering new content
       this.emit({ emit: 'render:clear' });
-    } else {
-      this.emit({ emit: 'render', format, value });
+      return;
     }
+
+    // UI feedback formats — emit native shapes the frontend already handles
+    switch (format) {
+      case 'status':
+        this.emit(typeof value === 'string'
+          ? { emit: 'status', message: value }
+          : { emit: 'status', ...value });
+        return;
+      case 'progress':
+        this.emit(typeof value === 'number'
+          ? { emit: 'progress', value }
+          : { emit: 'progress', ...value });
+        return;
+      case 'toast':
+        this.emit(typeof value === 'string'
+          ? { emit: 'toast', message: value }
+          : { emit: 'toast', ...value });
+        return;
+    }
+
+    // All other formats — generic render
+    this.emit({ emit: 'render', format, value });
+  }
+
+  /**
+   * Channel interface for communicating with connected clients (e.g. Claude Code).
+   * No-ops silently when the photon is not marked with @channel.
+   *
+   * Call directly to send a message:
+   *   this.channel('Hello', { chat_id: '123' })
+   *
+   * Use .respond() to answer permission requests:
+   *   this.channel.respond(request_id, 'allow')
+   *
+   * Use .onPermission() to handle incoming permission requests:
+   *   this.channel.onPermission((req) => { ... })
+   */
+  protected channel: {
+    (content: string, meta?: Record<string, string>): void;
+    respond(requestId: string, behavior: 'allow' | 'deny'): void;
+    onPermission(handler: (request: { request_id: string; tool_name: string; description: string; input_preview: string }) => void): void;
+  } = Object.assign(
+    (_content: string, _meta?: Record<string, string>) => {
+      // Injected by the loader — no-op by default
+    },
+    {
+      respond: (_requestId: string, _behavior: 'allow' | 'deny') => {
+        // Injected by the loader — no-op by default
+      },
+      onPermission: (_handler: (request: any) => void) => {
+        // Injected by the loader — no-op by default
+      },
+    }
+  );
+
+  /**
+   * Create a blocking input request for use in generator methods.
+   *
+   * Returns a yield object — use with `yield` in async generators:
+   * ```typescript
+   * const name = yield this.ask('text', 'What is your name?');
+   * ```
+   *
+   * @param type Input type: text, password, confirm, select, number, file, date, form, url
+   * @param message The prompt message shown to the user
+   * @param options Type-specific options (placeholder, pattern, min/max, etc.)
+   *
+   * @example
+   * ```typescript
+   * async *setup() {
+   *   const token = yield this.ask('password', 'Enter API key:');
+   *   const env = yield this.ask('select', 'Environment:', {
+   *     options: ['dev', 'staging', 'prod']
+   *   });
+   *   const confirmed = yield this.ask('confirm', `Deploy to ${env}?`);
+   * }
+   * ```
+   */
+  protected ask(type: string, message: string, options?: Record<string, any>): { ask: string; message: string; [key: string]: any } {
+    return { ask: type, message, ...options };
   }
 
   /**

package/src/compiler.ts

@@ -174,8 +174,17 @@ export async function compilePhotonTS(
   // Ensure cache directory exists
   await fs.mkdir(options.cacheDir, { recursive: true });
 
+  // Inject createRequire shim so CJS dependencies work in ESM context.
+  // This is needed for Node.js — Bun handles CJS/ESM interop natively.
+  const requireShim = `import { createRequire as __createRequire } from 'module';
+import { fileURLToPath as __fileURLToPath } from 'url';
+const __filename = __fileURLToPath(import.meta.url);
+const require = __createRequire(import.meta.url);
+`;
+  const code = requireShim + result.code;
+
   // Write compiled JavaScript
-  await fs.writeFile(cachedJsPath, result.code, 'utf-8');
+  await fs.writeFile(cachedJsPath, code, 'utf-8');
 
   return cachedJsPath;
 }

package/src/config.ts

@@ -1,69 +1,73 @@
 /**
  * Photon Configuration Utilities
  *
- * Provides standard config storage for photons that implement the configure() convention.
- * Config is stored at ~/.photon/{photonName}/config.json
+ * Provides standard config storage for photons.
+ * Config is stored at .data/{namespace}/{photonName}/config.json
  *
  * Usage in a Photon:
  * ```typescript
- * import { loadPhotonConfig, savePhotonConfig, getPhotonConfigPath } from '@portel/photon-core';
+ * import { loadPhotonConfig, savePhotonConfig } from '@portel/photon-core';
  *
  * export default class MyPhoton extends Photon {
  *   async configure(params: { apiKey: string }) {
  *     savePhotonConfig('my-photon', params);
  *     return { success: true, config: params };
  *   }
- *
- *   async getConfig() {
- *     return loadPhotonConfig('my-photon');
- *   }
  * }
  * ```
  */
 
 import * as fs from 'fs';
 import * as path from 'path';
-import * as os from 'os';
+
+import {
+  getPhotonConfigPath as getNewConfigPath,
+  getLegacyPhotonConfigPath,
+  getDataRoot,
+} from './data-paths.js';
 
 /**
- * Get the config directory for photons
- * Default: ~/.photon/
+ * Get the config file path for a specific photon.
+ * Uses new .data/ layout, falls back to legacy path for reads.
  */
-export function getPhotonConfigDir(): string {
-  return process.env.PHOTON_CONFIG_DIR || path.join(os.homedir(), '.photon');
+export function getPhotonConfigPath(photonName: string, namespace?: string): string {
+  const ns = namespace || 'local';
+  const newPath = getNewConfigPath(ns, photonName);
+
+  // Fallback: check legacy path for existing config
+  if (!fs.existsSync(newPath)) {
+    const legacyPath = getLegacyPhotonConfigPath(photonName);
+    if (fs.existsSync(legacyPath)) return legacyPath;
+  }
+
+  return newPath;
 }
 
 /**
- * Get the config file path for a specific photon
- * @param photonName The photon name (kebab-case)
- * @returns Path to config.json for this photon
+ * Get the config directory for photons (legacy compat)
+ * @deprecated Use getPhotonConfigPath with namespace instead
  */
-export function getPhotonConfigPath(photonName: string): string {
-  const safeName = photonName.replace(/[^a-zA-Z0-9_-]/g, '_');
-  return path.join(getPhotonConfigDir(), safeName, 'config.json');
+export function getPhotonConfigDir(): string {
+  return process.env.PHOTON_CONFIG_DIR || getDataRoot();
 }
 
 /**
  * Load configuration for a photon
- * @param photonName The photon name (kebab-case)
- * @param defaults Default values if config doesn't exist
- * @returns The config object or defaults
  */
 export function loadPhotonConfig<T extends Record<string, any>>(
   photonName: string,
-  defaults?: T
+  defaults?: T,
+  namespace?: string
 ): T {
-  const configPath = getPhotonConfigPath(photonName);
+  const configPath = getPhotonConfigPath(photonName, namespace);
 
   try {
     if (fs.existsSync(configPath)) {
       const content = fs.readFileSync(configPath, 'utf-8');
       const config = JSON.parse(content);
-      // Merge with defaults
       return defaults ? { ...defaults, ...config } : config;
     }
   } catch (error) {
-    // Log but don't throw - return defaults
     if (process.env.PHOTON_DEBUG) {
       console.error(`Failed to load config for ${photonName}:`, error);
     }
@@ -73,18 +77,17 @@ export function loadPhotonConfig<T extends Record<string, any>>(
 }
 
 /**
- * Save configuration for a photon
- * @param photonName The photon name (kebab-case)
- * @param config The configuration object to save
+ * Save configuration for a photon (always writes to new .data/ path)
  */
 export function savePhotonConfig<T extends Record<string, any>>(
   photonName: string,
-  config: T
+  config: T,
+  namespace?: string
 ): void {
-  const configPath = getPhotonConfigPath(photonName);
+  const ns = namespace || 'local';
+  const configPath = getNewConfigPath(ns, photonName);
   const configDir = path.dirname(configPath);
 
-  // Ensure directory exists
   if (!fs.existsSync(configDir)) {
     fs.mkdirSync(configDir, { recursive: true });
   }
@@ -94,19 +97,16 @@ export function savePhotonConfig<T extends Record<string, any>>(
 
 /**
  * Check if a photon has been configured
- * @param photonName The photon name (kebab-case)
- * @returns true if config file exists
  */
-export function hasPhotonConfig(photonName: string): boolean {
-  return fs.existsSync(getPhotonConfigPath(photonName));
+export function hasPhotonConfig(photonName: string, namespace?: string): boolean {
+  return fs.existsSync(getPhotonConfigPath(photonName, namespace));
 }
 
 /**
  * Delete configuration for a photon
- * @param photonName The photon name (kebab-case)
  */
-export function deletePhotonConfig(photonName: string): void {
-  const configPath = getPhotonConfigPath(photonName);
+export function deletePhotonConfig(photonName: string, namespace?: string): void {
+  const configPath = getPhotonConfigPath(photonName, namespace);
   if (fs.existsSync(configPath)) {
     fs.unlinkSync(configPath);
   }
@@ -114,21 +114,34 @@ export function deletePhotonConfig(photonName: string): void {
 
 /**
  * List all configured photons
- * @returns Array of photon names that have config
  */
 export function listConfiguredPhotons(): string[] {
-  const configDir = getPhotonConfigDir();
+  const dataRoot = getDataRoot();
 
-  if (!fs.existsSync(configDir)) {
+  if (!fs.existsSync(dataRoot)) {
     return [];
   }
 
+  const results: string[] = [];
   try {
-    return fs.readdirSync(configDir, { withFileTypes: true })
-      .filter(entry => entry.isDirectory())
-      .filter(entry => fs.existsSync(path.join(configDir, entry.name, 'config.json')))
-      .map(entry => entry.name);
+    // Scan namespace directories inside .data/
+    const nsDirs = fs.readdirSync(dataRoot, { withFileTypes: true })
+      .filter(e => e.isDirectory() && !e.name.startsWith('_') && !e.name.startsWith('.'));
+
+    for (const nsDir of nsDirs) {
+      const nsPath = path.join(dataRoot, nsDir.name);
+      const photonDirs = fs.readdirSync(nsPath, { withFileTypes: true })
+        .filter(e => e.isDirectory());
+
+      for (const pDir of photonDirs) {
+        if (fs.existsSync(path.join(nsPath, pDir.name, 'config.json'))) {
+          results.push(pDir.name);
+        }
+      }
+    }
   } catch {
-    return [];
+    // Data root doesn't exist or is unreadable
   }
+
+  return results;
 }