@portel/photon-core 2.17.5 → 2.18.0

package/src/data-paths.ts

@@ -0,0 +1,289 @@
+/**
+ * Central Data Path Resolver
+ *
+ * Single source of truth for ALL runtime data paths in photon.
+ * Everything lives under `.data/` inside the photon base directory.
+ *
+ * Structure:
+ *   {baseDir}/.data/
+ *     # Global
+ *     daemon.sock / .pid / .log
+ *     audit.jsonl
+ *     .metadata.json
+ *     .cache/
+ *     _global/                              ← global shared memory
+ *     _sessions/{sessionId}/{ns}/{photon}/  ← session-scoped memory
+ *     tasks/                                ← ephemeral async task state
+ *
+ *     # Per-photon (always namespaced)
+ *     {namespace}/{photon-name}/
+ *       state/{instance}/state.json + state.log
+ *       memory/
+ *       env.json
+ *       context.json
+ *       runs/
+ *       logs/
+ *       schedules/
+ *       config.json
+ */
+
+import * as path from 'path';
+import * as os from 'os';
+import { execSync } from 'child_process';
+
+const DEFAULT_BASE = path.join(os.homedir(), '.photon');
+
+function getBase(baseDir?: string): string {
+  return baseDir || process.env.PHOTON_DIR || DEFAULT_BASE;
+}
+
+// ── Root ─────────────────────────────────────────────────────────────────────
+
+/** Root of all runtime data: {baseDir}/.data/ */
+export function getDataRoot(baseDir?: string): string {
+  return path.join(getBase(baseDir), '.data');
+}
+
+// ── Per-Photon ───────────────────────────────────────────────────────────────
+
+/** Per-photon data root: .data/{photonName}/ for local, .data/{namespace}/{photonName}/ for marketplace */
+export function getPhotonDataDir(namespace: string, photonName: string, baseDir?: string): string {
+  if (!namespace || namespace === 'local') {
+    return path.join(getDataRoot(baseDir), photonName);
+  }
+  return path.join(getDataRoot(baseDir), namespace, photonName);
+}
+
+/** Instance state file: .data/{ns}/{name}/state/{instance}/state.json */
+export function getPhotonStatePath(namespace: string, photonName: string, instance: string, baseDir?: string): string {
+  return path.join(getPhotonDataDir(namespace, photonName, baseDir), 'state', instance || 'default', 'state.json');
+}
+
+/** Instance event log: .data/{ns}/{name}/state/{instance}/state.log */
+export function getPhotonStateLogPath(namespace: string, photonName: string, instance: string, baseDir?: string): string {
+  return path.join(getPhotonDataDir(namespace, photonName, baseDir), 'state', instance || 'default', 'state.log');
+}
+
+/** Per-photon memory directory: .data/{ns}/{name}/memory/ */
+export function getPhotonMemoryDir(namespace: string, photonName: string, baseDir?: string): string {
+  return path.join(getPhotonDataDir(namespace, photonName, baseDir), 'memory');
+}
+
+/** Per-photon env vars: .data/{ns}/{name}/env.json */
+export function getPhotonEnvPath(namespace: string, photonName: string, baseDir?: string): string {
+  return path.join(getPhotonDataDir(namespace, photonName, baseDir), 'env.json');
+}
+
+/** Current instance selector: .data/{ns}/{name}/context.json */
+export function getPhotonContextPath(namespace: string, photonName: string, baseDir?: string): string {
+  return path.join(getPhotonDataDir(namespace, photonName, baseDir), 'context.json');
+}
+
+/** Workflow checkpoint runs: .data/{ns}/{name}/runs/ */
+export function getPhotonRunsDir(namespace: string, photonName: string, baseDir?: string): string {
+  return path.join(getPhotonDataDir(namespace, photonName, baseDir), 'runs');
+}
+
+/** Execution audit logs: .data/{ns}/{name}/logs/ */
+export function getPhotonLogsDir(namespace: string, photonName: string, baseDir?: string): string {
+  return path.join(getPhotonDataDir(namespace, photonName, baseDir), 'logs');
+}
+
+/** Schedule definitions: .data/{ns}/{name}/schedules/ */
+export function getPhotonSchedulesDir(namespace: string, photonName: string, baseDir?: string): string {
+  return path.join(getPhotonDataDir(namespace, photonName, baseDir), 'schedules');
+}
+
+/** Per-photon config: .data/{ns}/{name}/config.json */
+export function getPhotonConfigPath(namespace: string, photonName: string, baseDir?: string): string {
+  return path.join(getPhotonDataDir(namespace, photonName, baseDir), 'config.json');
+}
+
+// ── Global ───────────────────────────────────────────────────────────────────
+
+/** Global shared memory: .data/_global/ */
+export function getGlobalMemoryDir(baseDir?: string): string {
+  return path.join(getDataRoot(baseDir), '_global');
+}
+
+/** Session-scoped memory: .data/_sessions/{sessionId}/{photon}/ or .data/_sessions/{sessionId}/{ns}/{photon}/ */
+export function getSessionMemoryDir(sessionId: string, namespace: string, photonName: string, baseDir?: string): string {
+  const safeSession = sessionId.replace(/[^a-zA-Z0-9_-]/g, '_');
+  if (!namespace || namespace === 'local') {
+    return path.join(getDataRoot(baseDir), '_sessions', safeSession, photonName);
+  }
+  return path.join(getDataRoot(baseDir), '_sessions', safeSession, namespace, photonName);
+}
+
+/** Compilation & marketplace cache: .data/.cache/ */
+export function getCacheDir(baseDir?: string): string {
+  return path.join(getDataRoot(baseDir), '.cache');
+}
+
+/** Ephemeral async task state: .data/tasks/ */
+export function getTasksDir(baseDir?: string): string {
+  return path.join(getDataRoot(baseDir), 'tasks');
+}
+
+/** Global audit log: .data/audit.jsonl */
+export function getAuditPath(baseDir?: string): string {
+  return path.join(getDataRoot(baseDir), 'audit.jsonl');
+}
+
+/** Marketplace install metadata: .data/.metadata.json */
+export function getMetadataPath(baseDir?: string): string {
+  return path.join(getDataRoot(baseDir), '.metadata.json');
+}
+
+// ── Daemon (always global ~/.photon/.data/) ──────────────────────────────────
+
+/** Daemon socket: always ~/.photon/.data/daemon.sock (global, one per user) */
+export function getDaemonSocketPath(): string {
+  if (process.platform === 'win32') {
+    return '\\\\.\\pipe\\photon-daemon';
+  }
+  return path.join(DEFAULT_BASE, '.data', 'daemon.sock');
+}
+
+/** Daemon PID file: always ~/.photon/.data/daemon.pid */
+export function getDaemonPidPath(): string {
+  return path.join(DEFAULT_BASE, '.data', 'daemon.pid');
+}
+
+/** Daemon log file: always ~/.photon/.data/daemon.log */
+export function getDaemonLogPath(): string {
+  return path.join(DEFAULT_BASE, '.data', 'daemon.log');
+}
+
+// ── Namespace Detection ──────────────────────────────────────────────────────
+
+/**
+ * Detect the namespace for a photon directory by reading git remote origin.
+ * Returns the owner/org from the remote URL, or '' if not a git repo.
+ *
+ * Examples:
+ *   git@github.com:portel-dev/photons.git     → 'portel-dev'
+ *   https://github.com/arul-kumar/my-photons  → 'arul-kumar'
+ *   (no git remote)                           → ''
+ */
+export function detectNamespace(dir: string): string {
+  try {
+    const remote = execSync('git remote get-url origin', {
+      cwd: dir,
+      encoding: 'utf-8',
+      timeout: 3000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+
+    // SSH: git@github.com:owner/repo.git
+    const sshMatch = remote.match(/git@[^:]+:([^/]+)\//);
+    if (sshMatch) return sshMatch[1];
+
+    // HTTPS: https://github.com/owner/repo[.git]
+    const httpsMatch = remote.match(/https?:\/\/[^/]+\/([^/]+)\//);
+    if (httpsMatch) return httpsMatch[1];
+  } catch {
+    // Not a git repo or no remote — expected
+  }
+  return '';
+}
+
+// ── Legacy Path Helpers (for migration fallback) ─────────────────────────────
+
+/** Old state path: {baseDir}/state/{photonName}/{instance}.json */
+export function getLegacyStatePath(photonName: string, instance: string, baseDir?: string): string {
+  return path.join(getBase(baseDir), 'state', photonName, `${instance || 'default'}.json`);
+}
+
+/** Old state log: {baseDir}/state/{photonName}/{instance}.log */
+export function getLegacyStateLogPath(photonName: string, instance: string, baseDir?: string): string {
+  return path.join(getBase(baseDir), 'state', photonName, `${instance || 'default'}.log`);
+}
+
+/** Old context path: {baseDir}/context/{photonName}.json */
+export function getLegacyContextPath(photonName: string, baseDir?: string): string {
+  return path.join(getBase(baseDir), 'context', `${photonName}.json`);
+}
+
+/** Old env path: {baseDir}/env/{photonName}.json */
+export function getLegacyEnvPath(photonName: string, baseDir?: string): string {
+  return path.join(getBase(baseDir), 'env', `${photonName}.json`);
+}
+
+/** Old memory dir: {baseDir}/data/{photonId}/ */
+export function getLegacyMemoryDir(photonName: string, baseDir?: string): string {
+  const safeName = photonName.replace(/[^a-zA-Z0-9_-]/g, '_');
+  return path.join(getBase(baseDir), 'data', safeName);
+}
+
+/** Old global memory: {baseDir}/data/_global/ */
+export function getLegacyGlobalMemoryDir(baseDir?: string): string {
+  return path.join(getBase(baseDir), 'data', '_global');
+}
+
+/** Old session memory: {baseDir}/sessions/{sessionId}/{photonId}/ */
+export function getLegacySessionMemoryDir(sessionId: string, photonName: string, baseDir?: string): string {
+  const safeName = photonName.replace(/[^a-zA-Z0-9_-]/g, '_');
+  const safeSession = sessionId.replace(/[^a-zA-Z0-9_-]/g, '_');
+  return path.join(getBase(baseDir), 'sessions', safeSession, safeName);
+}
+
+/** Old runs dir: ~/.photon/runs/ */
+export function getLegacyRunsDir(): string {
+  return path.join(DEFAULT_BASE, 'runs');
+}
+
+/** Old logs dir: ~/.photon/logs/{photonId}/ */
+export function getLegacyLogsDir(photonName: string): string {
+  return path.join(DEFAULT_BASE, 'logs', photonName);
+}
+
+/** Old tasks dir: ~/.photon/tasks/ */
+export function getLegacyTasksDir(): string {
+  return path.join(DEFAULT_BASE, 'tasks');
+}
+
+/** Old audit path: ~/.photon/audit.jsonl */
+export function getLegacyAuditPath(): string {
+  return path.join(DEFAULT_BASE, 'audit.jsonl');
+}
+
+/** Old metadata path: {baseDir}/.metadata.json */
+export function getLegacyMetadataPath(baseDir?: string): string {
+  return path.join(getBase(baseDir), '.metadata.json');
+}
+
+/** Old daemon socket: ~/.photon/daemon.sock */
+export function getLegacyDaemonSocketPath(): string {
+  if (process.platform === 'win32') {
+    return '\\\\.\\pipe\\photon-daemon';
+  }
+  return path.join(DEFAULT_BASE, 'daemon.sock');
+}
+
+/** Old daemon PID: ~/.photon/daemon.pid */
+export function getLegacyDaemonPidPath(): string {
+  return path.join(DEFAULT_BASE, 'daemon.pid');
+}
+
+/** Old daemon log: ~/.photon/daemon.log */
+export function getLegacyDaemonLogPath(): string {
+  return path.join(DEFAULT_BASE, 'daemon.log');
+}
+
+/** Old cache dir: {baseDir}/.cache/ or {baseDir}/cache/ */
+export function getLegacyCacheDir(baseDir?: string): string {
+  return path.join(getBase(baseDir), '.cache');
+}
+
+/** Old schedules dir: ~/.photon/schedules/{photonName}/ */
+export function getLegacySchedulesDir(photonName: string): string {
+  const safeName = photonName.replace(/[^a-zA-Z0-9_-]/g, '_');
+  return path.join(DEFAULT_BASE, 'schedules', safeName);
+}
+
+/** Old per-photon config: ~/.photon/{photonName}/config.json */
+export function getLegacyPhotonConfigPath(photonName: string): string {
+  const safeName = photonName.replace(/[^a-zA-Z0-9_-]/g, '_');
+  return path.join(DEFAULT_BASE, safeName, 'config.json');
+}

package/src/dependency-manager.ts

@@ -7,9 +7,9 @@
 
 import * as fs from 'fs/promises';
 import * as path from 'path';
-import * as os from 'os';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
+import { getCacheDir } from './data-paths.js';
 
 interface DependencySpec {
   name: string;
@@ -22,9 +22,8 @@ interface DependencySpec {
 export class DependencyManager {
   private cacheDir: string;
 
-  constructor() {
-    // Store dependencies in ~/.cache/photon-mcp/dependencies/
-    this.cacheDir = path.join(os.homedir(), '.cache', 'photon-mcp', 'dependencies');
+  constructor(cacheDir?: string) {
+    this.cacheDir = cacheDir || path.join(getCacheDir(), 'dependencies');
   }
 
   /**
@@ -155,10 +154,19 @@ export class DependencyManager {
         }
       }
 
-      // Check if node_modules exists
+      // Check if node_modules exists and has actual packages
       const nodeModules = path.join(mcpDir, 'node_modules');
       await fs.access(nodeModules);
 
+      // Verify at least one expected dependency is present (catches empty dirs from failed installs)
+      for (const dep of dependencies) {
+        try {
+          await fs.access(path.join(nodeModules, dep.name));
+        } catch {
+          return false; // Expected package missing — reinstall
+        }
+      }
+
       return true;
     } catch {
       return false;

package/src/index.ts

@@ -583,3 +583,7 @@ export {
   type FieldType as FormFieldType,
   type FormOptions,
 } from './ui-types/index.js';
+
+// ===== DATA PATHS =====
+// Central data path resolver — single source of truth for all runtime data locations
+export * from './data-paths.js';

package/src/instance-store.ts

@@ -4,46 +4,75 @@
  * Shared state persistence for named photon instances.
  * Used by daemon, NCP, and Lumina to manage per-instance state.
  *
- * Paths (matching daemon convention):
+ * Paths (new .data/ layout):
+ * - State: .data/{namespace}/{photonName}/state/{instance}/state.json
+ * - Context: .data/{namespace}/{photonName}/context.json
+ *
+ * Falls back to legacy paths for migration:
  * - State: ~/.photon/state/{photonName}/{instanceName}.json
- * - Context: ~/.photon/context/{photonName}.json → { current: "name" }
+ * - Context: ~/.photon/context/{photonName}.json
  */
 
 import * as fs from 'fs/promises';
 import * as fsSync from 'fs';
 import * as path from 'path';
-import * as os from 'os';
+
+import {
+  getPhotonStatePath,
+  getPhotonContextPath,
+  getPhotonDataDir,
+  getLegacyStatePath,
+  getLegacyContextPath,
+} from './data-paths.js';
 
 export interface InstanceStoreOptions {
   /** Base directory (default: ~/.photon) */
   baseDir?: string;
-}
-
-function getBaseDir(options?: InstanceStoreOptions): string {
-  return options?.baseDir || process.env.PHOTON_DIR || path.join(os.homedir(), '.photon');
+  /** Namespace (default: 'local') */
+  namespace?: string;
 }
 
 export class InstanceStore {
   private photonName: string;
-  private baseDir: string;
+  private namespace: string;
+  private baseDir?: string;
 
   constructor(photonName: string, options?: InstanceStoreOptions) {
     this.photonName = photonName;
-    this.baseDir = getBaseDir(options);
+    this.namespace = options?.namespace || 'local';
+    this.baseDir = options?.baseDir;
   }
 
   /**
-   * Get the state directory for this photon
+   * Get the state directory for this photon (new layout)
    */
   private stateDir(): string {
-    return path.join(this.baseDir, 'state', this.photonName);
+    return path.join(getPhotonDataDir(this.namespace, this.photonName, this.baseDir), 'state');
   }
 
   /**
-   * Get the context file path for this photon
+   * Get the context file path, with fallback to legacy
    */
   private contextPath(): string {
-    return path.join(this.baseDir, 'context', `${this.photonName}.json`);
+    const newPath = getPhotonContextPath(this.namespace, this.photonName, this.baseDir);
+    if (!fsSync.existsSync(newPath)) {
+      const legacyPath = getLegacyContextPath(this.photonName, this.baseDir);
+      if (fsSync.existsSync(legacyPath)) return legacyPath;
+    }
+    return newPath;
+  }
+
+  /**
+   * Resolve state file path with fallback to legacy
+   */
+  private resolveStatePath(instanceName: string): string {
+    const name = instanceName || 'default';
+    const newPath = getPhotonStatePath(this.namespace, this.photonName, name, this.baseDir);
+    if (!fsSync.existsSync(newPath)) {
+      const legacyPath = getLegacyStatePath(this.photonName, name, this.baseDir);
+      if (fsSync.existsSync(legacyPath)) return legacyPath;
+    }
+    return newPath;
   }
 
   /**
@@ -51,7 +80,21 @@ export class InstanceStore {
    */
   async list(): Promise<string[]> {
     try {
-      const files = await fs.readdir(this.stateDir());
+      // New layout: state/{instance}/ directories
+      const dir = this.stateDir();
+      const entries = await fs.readdir(dir, { withFileTypes: true });
+      const instances = entries
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name);
+      if (instances.length > 0) return instances;
+    } catch {
+      // Fall through to legacy
+    }
+
+    // Legacy: state/{photonName}/*.json files
+    try {
+      const legacyDir = path.dirname(getLegacyStatePath(this.photonName, 'default', this.baseDir));
+      const files = await fs.readdir(legacyDir);
       return files
         .filter((f) => f.endsWith('.json'))
         .map((f) => f.slice(0, -5));
@@ -76,10 +119,10 @@ export class InstanceStore {
   }
 
   /**
-   * Set the current instance name
+   * Set the current instance name (always writes to new path)
    */
   async setCurrent(instanceName: string): Promise<void> {
-    const filePath = this.contextPath();
+    const filePath = getPhotonContextPath(this.namespace, this.photonName, this.baseDir);
     await fs.mkdir(path.dirname(filePath), { recursive: true });
     await fs.writeFile(filePath, JSON.stringify({ current: instanceName }, null, 2));
   }
@@ -89,7 +132,7 @@ export class InstanceStore {
    */
   async load<T = Record<string, unknown>>(instanceName?: string): Promise<T | null> {
     const name = instanceName ?? await this.getCurrent();
-    const filePath = InstanceStore.statePath(this.photonName, name, this.baseDir);
+    const filePath = this.resolveStatePath(name);
     try {
       const content = await fs.readFile(filePath, 'utf-8');
       return JSON.parse(content) as T;
@@ -100,10 +143,10 @@ export class InstanceStore {
   }
 
   /**
-   * Save state for an instance
+   * Save state for an instance (always writes to new path)
    */
   async save(instanceName: string, state: Record<string, unknown>): Promise<void> {
-    const filePath = InstanceStore.statePath(this.photonName, instanceName, this.baseDir);
+    const filePath = getPhotonStatePath(this.namespace, this.photonName, instanceName, this.baseDir);
     await fs.mkdir(path.dirname(filePath), { recursive: true });
     await fs.writeFile(filePath, JSON.stringify(state, null, 2));
   }
@@ -112,7 +155,7 @@ export class InstanceStore {
    * Delete an instance's state
    */
   async delete(instanceName: string): Promise<boolean> {
-    const filePath = InstanceStore.statePath(this.photonName, instanceName, this.baseDir);
+    const filePath = this.resolveStatePath(instanceName);
     try {
       await fs.unlink(filePath);
       return true;
@@ -127,7 +170,7 @@ export class InstanceStore {
    */
   async exists(instanceName?: string): Promise<boolean> {
     const name = instanceName ?? await this.getCurrent();
-    const filePath = InstanceStore.statePath(this.photonName, name, this.baseDir);
+    const filePath = this.resolveStatePath(name);
     try {
       await fs.access(filePath);
       return true;
@@ -137,19 +180,16 @@ export class InstanceStore {
   }
 
   /**
-   * Get the file path for instance state
+   * Get the file path for instance state (new .data/ layout)
    */
-  static statePath(photonName: string, instanceName: string, baseDir?: string): string {
-    const dir = baseDir || getBaseDir();
-    const name = instanceName || 'default';
-    return path.join(dir, 'state', photonName, `${name}.json`);
+  static statePath(photonName: string, instanceName: string, baseDir?: string, namespace?: string): string {
+    return getPhotonStatePath(namespace || 'local', photonName, instanceName, baseDir);
   }
 
   /**
-   * Get the context file path for a photon
+   * Get the context file path for a photon (new .data/ layout)
    */
-  static contextPath(photonName: string, baseDir?: string): string {
-    const dir = baseDir || getBaseDir();
-    return path.join(dir, 'context', `${photonName}.json`);
+  static contextPath(photonName: string, baseDir?: string, namespace?: string): string {
+    return getPhotonContextPath(namespace || 'local', photonName, baseDir);
   }
 }