@allternit/gizzi-code 1.0.0

package/src/utils/sessionStorage.ts

@@ -0,0 +1,559 @@
+/**
+ * @fileoverview Session storage utilities for gizzi-code integration
+ * @module utils/sessionStorage
+ *
+ * Provides session persistence, storage management, and user type detection
+ * with safe fallbacks for environments without storage access.
+ */
+
+import type { UserSession } from '../state/AppStateStore';
+import type { TypedMessage } from '../types/message';
+
+/**
+ * Storage keys used throughout the application
+ * @constant {Record<string, string>}
+ */
+export const STORAGE_KEYS = {
+  SESSION: 'gizzi_session',
+  USER_TYPE: 'gizzi_user_type',
+  MESSAGES: 'gizzi_messages',
+  PREFERENCES: 'gizzi_preferences',
+  LAST_ACTIVITY: 'gizzi_last_activity',
+  SESSION_METADATA: 'gizzi_session_metadata',
+} as const;
+
+/**
+ * User type categories
+ * @typedef {'anonymous' | 'free' | 'pro' | 'enterprise' | 'admin'} UserType
+ */
+export type UserType = 'anonymous' | 'free' | 'pro' | 'enterprise' | 'admin';
+
+/**
+ * Valid user types for runtime validation
+ * @constant {readonly UserType[]}
+ */
+export const VALID_USER_TYPES: readonly UserType[] = [
+  'anonymous',
+  'free',
+  'pro',
+  'enterprise',
+  'admin',
+] as const;
+
+/**
+ * Session metadata stored alongside the session
+ * @interface SessionMetadata
+ */
+export interface SessionMetadata {
+  /** When the session was created */
+  readonly createdAt: string;
+
+  /** Last activity timestamp (ISO string) */
+  readonly lastActivity: string;
+
+  /** Number of messages in this session */
+  readonly messageCount: number;
+
+  /** Session version for migration purposes */
+  readonly version: number;
+
+  /** Device/browser information */
+  readonly deviceInfo?: {
+    readonly userAgent: string;
+    readonly platform: string;
+    readonly language: string;
+  };
+}
+
+/**
+ * Complete session data structure
+ * @interface SessionData
+ */
+export interface SessionData {
+  /** User session information */
+  readonly session: UserSession;
+
+  /** Session metadata */
+  readonly metadata: SessionMetadata;
+
+  /** Persisted messages */
+  readonly messages: readonly TypedMessage[];
+
+  /** User preferences */
+  readonly preferences: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Storage operation result
+ * @interface StorageResult
+ */
+export interface StorageResult<T> {
+  /** Whether the operation succeeded */
+  readonly success: boolean;
+
+  /** The data if successful, null otherwise */
+  readonly data: T | null;
+
+  /** Error message if failed */
+  readonly error: string | null;
+}
+
+/**
+ * Checks if localStorage/sessionStorage is available
+ * @returns {boolean} True if storage APIs are available
+ */
+function isStorageAvailable(): boolean {
+  try {
+    if (typeof window === 'undefined') {
+      return false;
+    }
+    const testKey = '__gizzi_storage_test__';
+    window.sessionStorage.setItem(testKey, 'test');
+    window.sessionStorage.removeItem(testKey);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Safely parses JSON with error handling
+ *
+ * @template T
+ * @param {string} json - JSON string to parse
+ * @param {T} [defaultValue] - Default value if parsing fails
+ * @returns {T | null} Parsed value or default/null on error
+ */
+function safeJsonParse<T>(json: string, defaultValue?: T): T | null {
+  try {
+    return JSON.parse(json) as T;
+  } catch {
+    return defaultValue ?? null;
+  }
+}
+
+/**
+ * Safely stringifies JSON with error handling
+ *
+ * @param {unknown} value - Value to stringify
+ * @returns {string | null} JSON string or null on error
+ */
+function safeJsonStringify(value: unknown): string | null {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * In-memory fallback storage when sessionStorage is unavailable
+ * @constant {Map<string, string>}
+ */
+const memoryStorage: Map<string, string> = new Map();
+
+/**
+ * Gets an item from storage (sessionStorage or memory fallback)
+ *
+ * @param {string} key - Storage key
+ * @returns {string | null} The stored value or null
+ */
+function getStorageItem(key: string): string | null {
+  if (isStorageAvailable()) {
+    return window.sessionStorage.getItem(key);
+  }
+  return memoryStorage.get(key) ?? null;
+}
+
+/**
+ * Sets an item in storage (sessionStorage or memory fallback)
+ *
+ * @param {string} key - Storage key
+ * @param {string} value - Value to store
+ * @returns {boolean} True if successful
+ */
+function setStorageItem(key: string, value: string): boolean {
+  try {
+    if (isStorageAvailable()) {
+      window.sessionStorage.setItem(key, value);
+    } else {
+      memoryStorage.set(key, value);
+    }
+    return true;
+  } catch (error) {
+    console.error(`Failed to set storage item '${key}':`, error);
+    return false;
+  }
+}
+
+/**
+ * Removes an item from storage
+ *
+ * @param {string} key - Storage key to remove
+ * @returns {boolean} True if successful
+ */
+function removeStorageItem(key: string): boolean {
+  try {
+    if (isStorageAvailable()) {
+      window.sessionStorage.removeItem(key);
+    } else {
+      memoryStorage.delete(key);
+    }
+    return true;
+  } catch (error) {
+    console.error(`Failed to remove storage item '${key}':`, error);
+    return false;
+  }
+}
+
+/**
+ * Saves the current session to storage
+ *
+ * @param {UserSession} session - The session to save
+ * @param {Object} [options] - Save options
+ * @param {TypedMessage[]} [options.messages] - Messages to persist
+ * @param {Record<string, unknown>} [options.preferences] - Preferences to persist
+ * @returns {StorageResult<void>} Result of the save operation
+ * @example
+ * ```typescript
+ * const result = saveSession(session, { messages, preferences });
+ * if (!result.success) {
+ *   console.error('Failed to save session:', result.error);
+ * }
+ * ```
+ */
+export function saveSession(
+  session: UserSession,
+  options: {
+    messages?: TypedMessage[];
+    preferences?: Record<string, unknown>;
+  } = {}
+): StorageResult<void> {
+  if (!session) {
+    return { success: false, data: null, error: 'Session is required' };
+  }
+
+  const existingMetadata = loadSessionMetadata();
+  const metadata: SessionMetadata = {
+    createdAt: existingMetadata?.createdAt ?? new Date().toISOString(),
+    lastActivity: new Date().toISOString(),
+    messageCount: options.messages?.length ?? 0,
+    version: 1,
+    deviceInfo: isStorageAvailable()
+      ? {
+          userAgent: navigator.userAgent,
+          platform: navigator.platform,
+          language: navigator.language,
+        }
+      : undefined,
+  };
+
+  const sessionData: SessionData = {
+    session,
+    metadata,
+    messages: options.messages ?? [],
+    preferences: options.preferences ?? {},
+  };
+
+  const serialized = safeJsonStringify(sessionData);
+  if (!serialized) {
+    return { success: false, data: null, error: 'Failed to serialize session data' };
+  }
+
+  if (!setStorageItem(STORAGE_KEYS.SESSION, serialized)) {
+    return { success: false, data: null, error: 'Failed to write to storage' };
+  }
+
+  // Also save user type separately for quick access
+  setStorageItem(STORAGE_KEYS.USER_TYPE, session.userType);
+  setStorageItem(STORAGE_KEYS.LAST_ACTIVITY, metadata.lastActivity);
+
+  return { success: true, data: undefined, error: null };
+}
+
+/**
+ * Loads the session from storage
+ *
+ * @returns {StorageResult<SessionData>} The loaded session data or error
+ * @example
+ * ```typescript
+ * const result = loadSession();
+ * if (result.success && result.data) {
+ *   const { session, messages } = result.data;
+ *   // Restore session...
+ * }
+ * ```
+ */
+export function loadSession(): StorageResult<SessionData> {
+  const serialized = getStorageItem(STORAGE_KEYS.SESSION);
+
+  if (!serialized) {
+    return { success: false, data: null, error: 'No session found in storage' };
+  }
+
+  const data = safeJsonParse<SessionData>(serialized);
+
+  if (!data) {
+    return { success: false, data: null, error: 'Failed to parse session data' };
+  }
+
+  // Validate session has not expired
+  if (data.session.expiresAt) {
+    const expiresAt = new Date(data.session.expiresAt);
+    if (expiresAt < new Date()) {
+      clearSession();
+      return { success: false, data: null, error: 'Session has expired' };
+    }
+  }
+
+  // Update last activity
+  const updatedMetadata: SessionMetadata = {
+    ...data.metadata,
+    lastActivity: new Date().toISOString(),
+  };
+
+  // Silently update last activity in storage
+  const updatedData: SessionData = { ...data, metadata: updatedMetadata };
+  const serializedUpdated = safeJsonStringify(updatedData);
+  if (serializedUpdated) {
+    setStorageItem(STORAGE_KEYS.SESSION, serializedUpdated);
+  }
+
+  return { success: true, data: updatedData, error: null };
+}
+
+/**
+ * Clears all session data from storage
+ *
+ * @returns {boolean} True if successful
+ * @example
+ * ```typescript
+ * clearSession(); // Logs out the user
+ * ```
+ */
+export function clearSession(): boolean {
+  const keysToRemove = [
+    STORAGE_KEYS.SESSION,
+    STORAGE_KEYS.USER_TYPE,
+    STORAGE_KEYS.MESSAGES,
+    STORAGE_KEYS.PREFERENCES,
+    STORAGE_KEYS.LAST_ACTIVITY,
+    STORAGE_KEYS.SESSION_METADATA,
+  ];
+
+  let allSuccess = true;
+  for (const key of keysToRemove) {
+    if (!removeStorageItem(key)) {
+      allSuccess = false;
+    }
+  }
+
+  // Also clear memory storage
+  memoryStorage.clear();
+
+  return allSuccess;
+}
+
+/**
+ * Gets the user type from storage
+ * Returns 'anonymous' if no user type is stored or on error
+ *
+ * @returns {UserType} The stored user type or 'anonymous'
+ * @example
+ * ```typescript
+ * const userType = getUserType();
+ * if (userType === 'pro') {
+ *   // Show pro features
+ * }
+ * ```
+ */
+export function getUserType(): UserType {
+  const stored = getStorageItem(STORAGE_KEYS.USER_TYPE);
+
+  if (stored && VALID_USER_TYPES.includes(stored as UserType)) {
+    return stored as UserType;
+  }
+
+  // Try to infer from session
+  const sessionResult = loadSession();
+  if (sessionResult.success && sessionResult.data) {
+    const sessionType = sessionResult.data.session.userType;
+    if (VALID_USER_TYPES.includes(sessionType as UserType)) {
+      return sessionType as UserType;
+    }
+  }
+
+  return 'anonymous';
+}
+
+/**
+ * Loads session metadata without loading the full session
+ *
+ * @returns {SessionMetadata | null} The metadata or null if not found
+ */
+function loadSessionMetadata(): SessionMetadata | null {
+  const sessionResult = loadSession();
+  if (sessionResult.success && sessionResult.data) {
+    return sessionResult.data.metadata;
+  }
+  return null;
+}
+
+/**
+ * Saves messages to session storage
+ *
+ * @param {TypedMessage[]} messages - Messages to save
+ * @returns {StorageResult<void>} Result of the operation
+ */
+export function saveMessages(messages: TypedMessage[]): StorageResult<void> {
+  const serialized = safeJsonStringify(messages);
+
+  if (!serialized) {
+    return { success: false, data: null, error: 'Failed to serialize messages' };
+  }
+
+  if (!setStorageItem(STORAGE_KEYS.MESSAGES, serialized)) {
+    return { success: false, data: null, error: 'Failed to write messages to storage' };
+  }
+
+  // Update message count in session metadata
+  const sessionResult = loadSession();
+  if (sessionResult.success && sessionResult.data) {
+    const { session, metadata, preferences } = sessionResult.data;
+    saveSession(session, {
+      messages,
+      preferences,
+    });
+  }
+
+  return { success: true, data: undefined, error: null };
+}
+
+/**
+ * Loads messages from session storage
+ *
+ * @returns {StorageResult<TypedMessage[]>} The loaded messages or error
+ */
+export function loadMessages(): StorageResult<TypedMessage[]> {
+  const serialized = getStorageItem(STORAGE_KEYS.MESSAGES);
+
+  if (!serialized) {
+    return { success: false, data: null, error: 'No messages found in storage' };
+  }
+
+  const messages = safeJsonParse<TypedMessage[]>(serialized, []);
+
+  if (!messages) {
+    return { success: false, data: null, error: 'Failed to parse messages' };
+  }
+
+  return { success: true, data: messages, error: null };
+}
+
+/**
+ * Saves user preferences to storage
+ *
+ * @param {Record<string, unknown>} preferences - Preferences to save
+ * @returns {StorageResult<void>} Result of the operation
+ */
+export function savePreferences(preferences: Record<string, unknown>): StorageResult<void> {
+  const serialized = safeJsonStringify(preferences);
+
+  if (!serialized) {
+    return { success: false, data: null, error: 'Failed to serialize preferences' };
+  }
+
+  if (!setStorageItem(STORAGE_KEYS.PREFERENCES, serialized)) {
+    return { success: false, data: null, error: 'Failed to write preferences to storage' };
+  }
+
+  return { success: true, data: undefined, error: null };
+}
+
+/**
+ * Loads user preferences from storage
+ *
+ * @returns {StorageResult<Record<string, unknown>>} The loaded preferences or error
+ */
+export function loadPreferences(): StorageResult<Record<string, unknown>> {
+  const serialized = getStorageItem(STORAGE_KEYS.PREFERENCES);
+
+  if (!serialized) {
+    return { success: false, data: null, error: 'No preferences found in storage' };
+  }
+
+  const preferences = safeJsonParse<Record<string, unknown>>(serialized, {});
+
+  if (!preferences) {
+    return { success: false, data: null, error: 'Failed to parse preferences' };
+  }
+
+  return { success: true, data: preferences, error: null };
+}
+
+/**
+ * Gets the timestamp of the last user activity
+ *
+ * @returns {Date | null} The last activity date or null if not found
+ */
+export function getLastActivity(): Date | null {
+  const stored = getStorageItem(STORAGE_KEYS.LAST_ACTIVITY);
+
+  if (!stored) {
+    return null;
+  }
+
+  try {
+    const date = new Date(stored);
+    return isNaN(date.getTime()) ? null : date;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Updates the last activity timestamp to now
+ *
+ * @returns {boolean} True if successful
+ */
+export function updateLastActivity(): boolean {
+  return setStorageItem(STORAGE_KEYS.LAST_ACTIVITY, new Date().toISOString());
+}
+
+/**
+ * Checks if there is an active session in storage
+ *
+ * @returns {boolean} True if a valid session exists
+ */
+export function hasActiveSession(): boolean {
+  const result = loadSession();
+  return result.success;
+}
+
+/**
+ * Type guard to check if a value is a valid UserType
+ *
+ * @param {unknown} value - The value to check
+ * @returns {boolean} True if the value is a valid UserType
+ */
+export function isUserType(value: unknown): value is UserType {
+  return typeof value === 'string' && VALID_USER_TYPES.includes(value as UserType);
+}
+
+// Default export
+export default {
+  STORAGE_KEYS,
+  VALID_USER_TYPES,
+  saveSession,
+  loadSession,
+  clearSession,
+  getUserType,
+  saveMessages,
+  loadMessages,
+  savePreferences,
+  loadPreferences,
+  getLastActivity,
+  updateLastActivity,
+  hasActiveSession,
+  isUserType,
+};

package/src/watcher/WorkspaceWatcher.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Gizzi Workspace File Watcher
+ *
+ * Monitors agent workspace files for changes and triggers context refresh.
+ */
+import type { FileSystem } from '../workspace/loader';
+export interface FileChange {
+    path: string;
+    type: 'created' | 'modified' | 'deleted';
+    previousModTime?: Date;
+    currentModTime?: Date;
+}
+export interface WatcherOptions {
+    pollIntervalMs: number;
+    onChange: (changes: FileChange[]) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Workspace File Watcher for Gizzi
+ */
+export declare class WorkspaceWatcher {
+    private agentId;
+    private basePath;
+    private fs;
+    private options;
+    private intervalId;
+    private watchedFiles;
+    private isWatching;
+    constructor(agentId: string, basePath: string, fs: FileSystem, options?: Partial<WatcherOptions>);
+    /**
+     * Start watching for changes
+     */
+    start(): Promise<void>;
+    /**
+     * Stop watching
+     */
+    stop(): void;
+    /**
+     * Get current watch status
+     */
+    getStatus(): {
+        isWatching: boolean;
+        filesWatched: number;
+    };
+    /**
+     * Force a manual refresh
+     */
+    refresh(): Promise<FileChange[]>;
+    /**
+     * Scan workspace for files
+     */
+    private scanWorkspace;
+    /**
+     * Check for changes
+     */
+    private checkForChanges;
+}
+/**
+ * Get or create a watcher for an agent
+ */
+export declare function getWorkspaceWatcher(agentId: string, basePath: string, fs: FileSystem, options?: Partial<WatcherOptions>): WorkspaceWatcher;
+/**
+ * Stop all watchers
+ */
+export declare function stopAllWatchers(): void;
+export declare const workspaceWatcher: {
+    watchers: Map<string, WorkspaceWatcher>;
+    getWatcher: typeof getWorkspaceWatcher;
+    stopAll: typeof stopAllWatchers;
+};