@portel/photon-core 2.17.6 → 2.18.0

package/src/memory.ts

@@ -5,11 +5,11 @@
  * boilerplate file I/O. Available as `this.memory` on Photon.
  *
  * Three scopes:
- * | Scope    | Meaning                          | Storage                           |
- * |----------|----------------------------------|-----------------------------------|
- * | photon   | Private to this photon (default)  | ~/.photon/data/{photonId}/        |
- * | session  | Per-user session (Beam sessions)  | ~/.photon/sessions/{sessionId}/   |
- * | global   | Shared across all photons         | ~/.photon/data/_global/           |
+ * | Scope    | Meaning                          | Storage                                       |
+ * |----------|----------------------------------|-----------------------------------------------|
+ * | photon   | Private to this photon (default)  | .data/{namespace}/{photonName}/memory/         |
+ * | session  | Per-user session (Beam sessions)  | .data/_sessions/{sessionId}/{ns}/{photon}/     |
+ * | global   | Shared across all photons         | .data/_global/                                |
  *
  * @example
  * ```typescript
@@ -25,42 +25,60 @@
  */
 
 import * as fs from 'fs/promises';
+import * as fsSync from 'fs';
 import * as path from 'path';
-import * as os from 'os';
 
-export type MemoryScope = 'photon' | 'session' | 'global';
-
-/**
- * Get the base data directory
- */
-function getDataDir(): string {
-  return process.env.PHOTON_DATA_DIR || path.join(os.homedir(), '.photon', 'data');
-}
+import {
+  getPhotonMemoryDir,
+  getGlobalMemoryDir,
+  getSessionMemoryDir,
+  getLegacyMemoryDir,
+  getLegacyGlobalMemoryDir,
+  getLegacySessionMemoryDir,
+} from './data-paths.js';
 
-/**
- * Get the sessions directory
- */
-function getSessionsDir(): string {
-  return process.env.PHOTON_SESSIONS_DIR || path.join(os.homedir(), '.photon', 'sessions');
-}
+export type MemoryScope = 'photon' | 'session' | 'global';
 
 /**
- * Resolve storage directory for a given scope
+ * Resolve storage directory for a given scope.
+ * Uses new .data/ paths with fallback to legacy locations.
  */
-function resolveDir(photonId: string, scope: MemoryScope, sessionId?: string): string {
-  const safeName = photonId.replace(/[^a-zA-Z0-9_-]/g, '_');
-
+function resolveDir(
+  photonId: string,
+  namespace: string,
+  scope: MemoryScope,
+  sessionId?: string,
+  baseDir?: string
+): string {
   switch (scope) {
-    case 'photon':
-      return path.join(getDataDir(), safeName);
-    case 'session':
+    case 'photon': {
+      const newDir = getPhotonMemoryDir(namespace, photonId, baseDir);
+      // Fallback: check legacy path if new path has no data yet
+      if (!fsSync.existsSync(newDir)) {
+        const legacyDir = getLegacyMemoryDir(photonId, baseDir);
+        if (fsSync.existsSync(legacyDir)) return legacyDir;
+      }
+      return newDir;
+    }
+    case 'session': {
       if (!sessionId) {
         throw new Error('Session ID required for session-scoped memory. Set via memory.sessionId.');
       }
-      const safeSession = sessionId.replace(/[^a-zA-Z0-9_-]/g, '_');
-      return path.join(getSessionsDir(), safeSession, safeName);
-    case 'global':
-      return path.join(getDataDir(), '_global');
+      const newDir = getSessionMemoryDir(sessionId, namespace, photonId, baseDir);
+      if (!fsSync.existsSync(newDir)) {
+        const legacyDir = getLegacySessionMemoryDir(sessionId, photonId, baseDir);
+        if (fsSync.existsSync(legacyDir)) return legacyDir;
+      }
+      return newDir;
+    }
+    case 'global': {
+      const newDir = getGlobalMemoryDir(baseDir);
+      if (!fsSync.existsSync(newDir)) {
+        const legacyDir = getLegacyGlobalMemoryDir(baseDir);
+        if (fsSync.existsSync(legacyDir)) return legacyDir;
+      }
+      return newDir;
+    }
     default:
       throw new Error(`Unknown memory scope: ${scope}`);
   }
@@ -94,11 +112,15 @@ async function pathExists(p: string): Promise<boolean> {
  */
 export class MemoryProvider {
   private _photonId: string;
+  private _namespace: string;
   private _sessionId?: string;
+  private _baseDir?: string;
 
-  constructor(photonId: string, sessionId?: string) {
+  constructor(photonId: string, sessionId?: string, namespace?: string, baseDir?: string) {
     this._photonId = photonId;
+    this._namespace = namespace || 'local';
     this._sessionId = sessionId;
+    this._baseDir = baseDir;
   }
 
   /**
@@ -120,7 +142,7 @@ export class MemoryProvider {
    * @returns The stored value, or null if not found
    */
   async get<T = any>(key: string, scope: MemoryScope = 'photon'): Promise<T | null> {
-    const dir = resolveDir(this._photonId, scope, this._sessionId);
+    const dir = resolveDir(this._photonId, this._namespace, scope, this._sessionId, this._baseDir);
     const filePath = keyPath(dir, key);
 
     try {
@@ -140,7 +162,7 @@ export class MemoryProvider {
    * @param scope Storage scope (default: 'photon')
    */
   async set<T = any>(key: string, value: T, scope: MemoryScope = 'photon'): Promise<void> {
-    const dir = resolveDir(this._photonId, scope, this._sessionId);
+    const dir = resolveDir(this._photonId, this._namespace, scope, this._sessionId, this._baseDir);
 
     if (!await pathExists(dir)) {
       await fs.mkdir(dir, { recursive: true });
@@ -158,7 +180,7 @@ export class MemoryProvider {
    * @returns true if the key existed and was deleted
    */
   async delete(key: string, scope: MemoryScope = 'photon'): Promise<boolean> {
-    const dir = resolveDir(this._photonId, scope, this._sessionId);
+    const dir = resolveDir(this._photonId, this._namespace, scope, this._sessionId, this._baseDir);
     const filePath = keyPath(dir, key);
 
     try {
@@ -177,7 +199,7 @@ export class MemoryProvider {
    * @param scope Storage scope (default: 'photon')
    */
   async has(key: string, scope: MemoryScope = 'photon'): Promise<boolean> {
-    const dir = resolveDir(this._photonId, scope, this._sessionId);
+    const dir = resolveDir(this._photonId, this._namespace, scope, this._sessionId, this._baseDir);
     return pathExists(keyPath(dir, key));
   }
 
@@ -187,7 +209,7 @@ export class MemoryProvider {
    * @param scope Storage scope (default: 'photon')
    */
   async keys(scope: MemoryScope = 'photon'): Promise<string[]> {
-    const dir = resolveDir(this._photonId, scope, this._sessionId);
+    const dir = resolveDir(this._photonId, this._namespace, scope, this._sessionId, this._baseDir);
 
     try {
       const files = await fs.readdir(dir);
@@ -206,7 +228,7 @@ export class MemoryProvider {
    * @param scope Storage scope (default: 'photon')
    */
   async clear(scope: MemoryScope = 'photon'): Promise<void> {
-    const dir = resolveDir(this._photonId, scope, this._sessionId);
+    const dir = resolveDir(this._photonId, this._namespace, scope, this._sessionId, this._baseDir);
 
     try {
       const files = await fs.readdir(dir);

package/src/mixins.ts

@@ -57,6 +57,7 @@ export function withPhotonCapabilities<T extends Constructor>(Base: T): T {
      * @internal
      */
     _photonName?: string;
+    _photonNamespace?: string;
 
     /**
      * Session ID for session-scoped memory - set by runtime
@@ -112,7 +113,7 @@ export function withPhotonCapabilities<T extends Constructor>(Base: T): T {
           .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;
     }
@@ -134,14 +135,34 @@ export function withPhotonCapabilities<T extends Constructor>(Base: T): T {
 
     /**
      * Render a formatted value as an intermediate result.
+     * Supports UI feedback formats (status, progress, toast) and data formats (table, qr, etc.).
      * Each call replaces the previous render. Call with no args to clear.
      */
     protected render(format?: string, value?: any): void {
       if (format === undefined) {
         this.emit({ emit: 'render:clear' });
-      } else {
-        this.emit({ emit: 'render', format, value });
+        return;
       }
+      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;
+      }
+      this.emit({ emit: 'render', format, value });
+    }
+
+    /**
+     * Create a blocking input request for use in generator methods.
+     * Returns a yield object: `const name = yield this.ask('text', 'Name?');`
+     */
+    protected ask(type: string, message: string, options?: Record<string, any>): { ask: string; message: string; [key: string]: any } {
+      return { ask: type, message, ...options };
     }
 
     /**

package/src/path-resolver.ts

@@ -14,6 +14,7 @@
  */
 
 import * as fs from 'fs/promises';
+import * as fsSync from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 
@@ -47,7 +48,8 @@ const defaultOptions: Required<ResolverOptions> = {
 
 /** Directories to skip when scanning for namespace subdirectories */
 const SKIP_DIRS = new Set([
-  'state', 'context', 'env', '.cache', '.config',
+  '.data', '.cache', '.config',
+  'state', 'context', 'env', // legacy data dirs (pre-.data/ consolidation)
   'node_modules', 'marketplace', 'photons', 'templates',
 ]);
 
@@ -243,12 +245,60 @@ export async function listFilesWithNamespace(
   return results;
 }
 
+/** Runtime data patterns that should never be committed to a marketplace repo */
+const GITIGNORE_DATA_PATTERNS = [
+  '# Photon runtime data (auto-generated)',
+  '.data/',
+];
+
+/**
+ * Check if a directory is inside a git repository
+ */
+function isGitRepo(dir: string): boolean {
+  let current = dir;
+  while (true) {
+    if (fsSync.existsSync(path.join(current, '.git'))) return true;
+    const parent = path.dirname(current);
+    if (parent === current) return false;
+    current = parent;
+  }
+}
+
+/**
+ * Ensure .gitignore in a git-tracked photon dir excludes runtime data.
+ * Only adds missing patterns — never removes or overwrites existing entries.
+ */
+async function ensureGitignore(dir: string): Promise<void> {
+  const gitignorePath = path.join(dir, '.gitignore');
+  let existing = '';
+  try {
+    existing = await fs.readFile(gitignorePath, 'utf-8');
+  } catch {
+    // No .gitignore yet
+  }
+
+  const existingLines = new Set(existing.split('\n').map((l) => l.trim()));
+  const missing = GITIGNORE_DATA_PATTERNS.filter((p) => !existingLines.has(p));
+
+  if (missing.length === 0) return;
+
+  const append = (existing && !existing.endsWith('\n') ? '\n' : '') + missing.join('\n') + '\n';
+  await fs.appendFile(gitignorePath, append);
+}
+
 /**
- * Ensure directory exists
+ * Ensure directory exists.
+ * If the directory is inside a git repo (e.g., a marketplace repo),
+ * auto-generates .gitignore entries for runtime data directories.
  */
 export async function ensureDir(dir?: string): Promise<void> {
   const targetDir = expandTilde(dir || DEFAULT_PHOTON_DIR);
   await fs.mkdir(targetDir, { recursive: true });
+
+  // Auto-exclude runtime data when developing in a git-tracked marketplace repo
+  if (targetDir !== DEFAULT_PHOTON_DIR && isGitRepo(targetDir)) {
+    await ensureGitignore(targetDir);
+  }
 }
 
 // Convenience aliases for photon-specific usage

package/src/photon-loader-lite.ts

@@ -38,6 +38,7 @@ import { ScheduleProvider } from './schedule.js';
 import { toEnvVarName, parseEnvValue, type MissingParamInfo } from './env-utils.js';
 import type { ExtractedSchema } from './types.js';
 import type { MCPClientFactory } from '@portel/mcp';
+import { getCacheDir } from './data-paths.js';
 
 // ═══════════════════════════════════════════════════════════════════
 // Types
@@ -54,6 +55,8 @@ export interface PhotonOptions {
   onEvent?: (event: PhotonEvent) => void;
   /** Session ID for session-scoped memory */
   sessionId?: string;
+  /** Namespace for data path resolution (marketplace owner). Defaults to 'local'. */
+  namespace?: string;
 }
 
 export interface PhotonEvent {
@@ -154,9 +157,7 @@ async function loadPhotonInternal(
     const source = await fs.readFile(absolutePath, 'utf-8');
 
     // 2. Compile TypeScript → JavaScript
-    const homeDir = process.env.HOME || process.env.USERPROFILE || '';
-    const cacheDir = path.join(homeDir, '.photon', 'cache');
-    const compiledPath = await compilePhotonTS(absolutePath, { cacheDir });
+    const compiledPath = await compilePhotonTS(absolutePath, { cacheDir: getCacheDir() });
 
     // 3. Import compiled module
     const moduleUrl = pathToFileURL(compiledPath).href;
@@ -193,6 +194,7 @@ async function loadPhotonInternal(
 
     // 10. Set photon identity
     instance._photonName = photonName;
+    instance._photonNamespace = options.namespace || 'local';
     if (options.instanceName) {
       instance.instanceName = options.instanceName;
     }

package/src/schedule.ts

@@ -31,6 +31,9 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import * as os from 'os';
+import * as fsSync from 'fs';
+
+import { getPhotonSchedulesDir, getLegacySchedulesDir } from './data-paths.js';
 import { randomUUID } from 'crypto';
 
 // ── Types ──────────────────────────────────────────────────────────────
@@ -136,13 +139,14 @@ function resolveCron(schedule: string): string {
 
 // ── Storage Helpers ────────────────────────────────────────────────────
 
-function getSchedulesDir(): string {
-  return process.env.PHOTON_SCHEDULES_DIR || path.join(os.homedir(), '.photon', 'schedules');
-}
-
-function photonScheduleDir(photonId: string): string {
-  const safeName = photonId.replace(/[^a-zA-Z0-9_-]/g, '_');
-  return path.join(getSchedulesDir(), safeName);
+function photonScheduleDir(photonId: string, namespace?: string): string {
+  const ns = namespace || 'local';
+  const newDir = getPhotonSchedulesDir(ns, photonId);
+  if (!fsSync.existsSync(newDir)) {
+    const legacyDir = getLegacySchedulesDir(photonId);
+    if (fsSync.existsSync(legacyDir)) return legacyDir;
+  }
+  return newDir;
 }
 
 function taskPath(photonId: string, taskId: string): string {

package/src/schema-extractor.ts

@@ -2365,7 +2365,7 @@ export class SchemaExtractor {
     if (['metric', 'gauge', 'progress', 'badge', 'timeline', 'dashboard', 'cart', 'qr', 'slides',
          'steps', 'stepper', 'log', 'image', 'hero', 'banner', 'quote', 'profile', 'heatmap',
          'kanban', 'calendar', 'map', 'cron', 'comparison', 'invoice', 'receipt', 'network', 'graph',
-         'checklist', 'article', 'magazine'].includes(format)) {
+         'checklist', 'article', 'magazine', 'guide'].includes(format)) {
       return format as OutputFormat;
     }
 

package/src/stateful.ts

@@ -54,6 +54,8 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import * as os from 'os';
+
+import { getPhotonRunsDir, getLegacyRunsDir } from './data-paths.js';
 import { createReadStream } from 'fs';
 import { createInterface } from 'readline';
 import { executionContext } from '@portel/cli';
@@ -85,9 +87,10 @@ import {
 // ══════════════════════════════════════════════════════════════════════════════
 
 /**
- * Default runs directory (~/.photon/runs)
+ * Default runs directory (legacy: ~/.photon/runs)
+ * @deprecated Use getPhotonRunsDir(namespace, photonName) from data-paths.ts
  */
-export const RUNS_DIR = path.join(os.homedir(), '.photon', 'runs');
+export const RUNS_DIR = getLegacyRunsDir();
 
 // ══════════════════════════════════════════════════════════════════════════════
 // CHECKPOINT YIELD TYPE