agileflow 3.4.3 → 4.0.0-alpha.2

package/lib/session-state-machine.js

@@ -1,465 +0,0 @@
-/**
- * Session State Machine
- *
- * Provides type-safe state transitions for AgileFlow sessions.
- * Enforces valid state changes and emits events on transitions.
- *
- * States:
- * - idle: Session created but not started
- * - active: Session is running
- * - paused: Session temporarily suspended
- * - terminated: Session has ended
- *
- * Valid Transitions:
- * - idle → active (start)
- * - active → paused (pause)
- * - active → terminated (stop)
- * - paused → active (resume)
- * - paused → terminated (stop)
- *
- * Usage:
- *   const { SessionStateMachine, SessionState } = require('./session-state-machine');
- *
- *   const sm = new SessionStateMachine('idle');
- *   sm.on('transition', ({ from, to, action }) => {
- *     console.log(`Transition: ${from} -[${action}]-> ${to}`);
- *   });
- *
- *   sm.canTransition('start');  // true
- *   sm.transition('start');     // State is now 'active'
- */
-
-'use strict';
-
-const EventEmitter = require('events');
-
-/**
- * Valid session states
- * @enum {string}
- */
-const SessionState = Object.freeze({
-  IDLE: 'idle',
-  ACTIVE: 'active',
-  PAUSED: 'paused',
-  TERMINATED: 'terminated',
-});
-
-/**
- * Valid state transition actions
- * @enum {string}
- */
-const SessionAction = Object.freeze({
-  START: 'start',
-  PAUSE: 'pause',
-  RESUME: 'resume',
-  STOP: 'stop',
-  RESTART: 'restart',
-});
-
-/**
- * State transition table
- * Maps current state → action → next state
- */
-const TRANSITIONS = Object.freeze({
-  [SessionState.IDLE]: {
-    [SessionAction.START]: SessionState.ACTIVE,
-  },
-  [SessionState.ACTIVE]: {
-    [SessionAction.PAUSE]: SessionState.PAUSED,
-    [SessionAction.STOP]: SessionState.TERMINATED,
-    [SessionAction.RESTART]: SessionState.ACTIVE, // Self-transition for restart
-  },
-  [SessionState.PAUSED]: {
-    [SessionAction.RESUME]: SessionState.ACTIVE,
-    [SessionAction.STOP]: SessionState.TERMINATED,
-  },
-  [SessionState.TERMINATED]: {
-    // No transitions out of terminated (final state)
-  },
-});
-
-/**
- * Get all valid states
- * @returns {string[]}
- */
-function getValidStates() {
-  return Object.values(SessionState);
-}
-
-/**
- * Get all valid actions
- * @returns {string[]}
- */
-function getValidActions() {
-  return Object.values(SessionAction);
-}
-
-/**
- * Check if a state is valid
- * @param {string} state
- * @returns {boolean}
- */
-function isValidState(state) {
-  return getValidStates().includes(state);
-}
-
-/**
- * Check if an action is valid
- * @param {string} action
- * @returns {boolean}
- */
-function isValidAction(action) {
-  return getValidActions().includes(action);
-}
-
-/**
- * Get valid transitions from a state
- * @param {string} state - Current state
- * @returns {Object} Map of action → next state
- */
-function getTransitionsFromState(state) {
-  return TRANSITIONS[state] || {};
-}
-
-/**
- * Get available actions from a state
- * @param {string} state - Current state
- * @returns {string[]} Available actions
- */
-function getAvailableActions(state) {
-  return Object.keys(getTransitionsFromState(state));
-}
-
-/**
- * Check if a transition is valid
- * @param {string} currentState - Current state
- * @param {string} action - Action to perform
- * @returns {boolean}
- */
-function canTransition(currentState, action) {
-  const transitions = TRANSITIONS[currentState];
-  return !!(transitions && transitions[action]);
-}
-
-/**
- * Get the next state for a transition
- * @param {string} currentState - Current state
- * @param {string} action - Action to perform
- * @returns {string|null} Next state or null if invalid
- */
-function getNextState(currentState, action) {
-  const transitions = TRANSITIONS[currentState];
-  return (transitions && transitions[action]) || null;
-}
-
-/**
- * Session state machine error
- */
-class StateMachineError extends Error {
-  constructor(message, details = {}) {
-    super(message);
-    this.name = 'StateMachineError';
-    this.currentState = details.currentState;
-    this.action = details.action;
-    this.code = details.code || 'INVALID_TRANSITION';
-  }
-}
-
-/**
- * Session State Machine
- * @extends EventEmitter
- *
- * Events:
- * - 'transition': { from, to, action, timestamp }
- * - 'invalidTransition': { currentState, action, error }
- * - 'stateChange': { state }
- */
-class SessionStateMachine extends EventEmitter {
-  /**
-   * @param {string} [initialState='idle'] - Initial state
-   * @param {Object} [options={}] - Options
-   * @param {boolean} [options.strict=true] - Throw on invalid transitions
-   * @param {boolean} [options.historyEnabled=false] - Track transition history
-   */
-  constructor(initialState = SessionState.IDLE, options = {}) {
-    super();
-
-    // Validate initial state
-    if (!isValidState(initialState)) {
-      throw new StateMachineError(`Invalid initial state: ${initialState}`, {
-        code: 'INVALID_STATE',
-      });
-    }
-
-    this._state = initialState;
-    this._strict = options.strict !== false;
-    this._historyEnabled = options.historyEnabled || false;
-    this._history = this._historyEnabled ? [{ state: initialState, timestamp: new Date() }] : [];
-    this._metadata = {};
-  }
-
-  /**
-   * Get current state
-   * @returns {string}
-   */
-  get state() {
-    return this._state;
-  }
-
-  /**
-   * Get transition history (if enabled)
-   * @returns {Array<{state: string, action?: string, timestamp: Date}>}
-   */
-  get history() {
-    return [...this._history];
-  }
-
-  /**
-   * Get metadata
-   * @returns {Object}
-   */
-  get metadata() {
-    return { ...this._metadata };
-  }
-
-  /**
-   * Set metadata
-   * @param {Object} meta - Metadata to merge
-   */
-  setMetadata(meta) {
-    this._metadata = { ...this._metadata, ...meta };
-  }
-
-  /**
-   * Check if state machine is in a final state
-   * @returns {boolean}
-   */
-  isFinal() {
-    return this._state === SessionState.TERMINATED;
-  }
-
-  /**
-   * Check if a transition can be performed
-   * @param {string} action - Action to check
-   * @returns {boolean}
-   */
-  canTransition(action) {
-    return canTransition(this._state, action);
-  }
-
-  /**
-   * Get available actions from current state
-   * @returns {string[]}
-   */
-  getAvailableActions() {
-    return getAvailableActions(this._state);
-  }
-
-  /**
-   * Perform a transition
-   * @param {string} action - Action to perform
-   * @returns {{ok: boolean, from?: string, to?: string, error?: Error}}
-   */
-  transition(action) {
-    const from = this._state;
-
-    // Check if action is valid
-    if (!isValidAction(action)) {
-      const error = new StateMachineError(`Invalid action: ${action}`, {
-        currentState: from,
-        action,
-        code: 'INVALID_ACTION',
-      });
-
-      this.emit('invalidTransition', { currentState: from, action, error });
-
-      if (this._strict) {
-        throw error;
-      }
-      return { ok: false, error };
-    }
-
-    // Check if transition is valid
-    const to = getNextState(from, action);
-
-    if (!to) {
-      const error = new StateMachineError(
-        `Cannot perform '${action}' from state '${from}'. Available actions: ${this.getAvailableActions().join(', ') || 'none'}`,
-        {
-          currentState: from,
-          action,
-          code: 'INVALID_TRANSITION',
-        }
-      );
-
-      this.emit('invalidTransition', { currentState: from, action, error });
-
-      if (this._strict) {
-        throw error;
-      }
-      return { ok: false, error };
-    }
-
-    // Perform transition
-    this._state = to;
-
-    const timestamp = new Date();
-
-    if (this._historyEnabled) {
-      this._history.push({ state: to, action, from, timestamp });
-    }
-
-    // Emit events
-    this.emit('transition', { from, to, action, timestamp });
-    this.emit('stateChange', { state: to });
-
-    return { ok: true, from, to };
-  }
-
-  /**
-   * Attempt transition without throwing on failure
-   * @param {string} action - Action to perform
-   * @returns {boolean} True if transition succeeded
-   */
-  tryTransition(action) {
-    try {
-      const result = this.transition(action);
-      return result.ok;
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Reset to initial state
-   * @param {string} [state='idle'] - State to reset to
-   */
-  reset(state = SessionState.IDLE) {
-    if (!isValidState(state)) {
-      throw new StateMachineError(`Invalid state: ${state}`, {
-        code: 'INVALID_STATE',
-      });
-    }
-
-    const from = this._state;
-    this._state = state;
-
-    if (this._historyEnabled) {
-      this._history.push({ state, action: 'reset', from, timestamp: new Date() });
-    }
-
-    this.emit('transition', { from, to: state, action: 'reset', timestamp: new Date() });
-    this.emit('stateChange', { state });
-  }
-
-  /**
-   * Check if state matches
-   * @param {string} state - State to check
-   * @returns {boolean}
-   */
-  is(state) {
-    return this._state === state;
-  }
-
-  /**
-   * Check if state is one of given states
-   * @param {...string} states - States to check
-   * @returns {boolean}
-   */
-  isOneOf(...states) {
-    return states.includes(this._state);
-  }
-
-  /**
-   * Serialize state machine
-   * @returns {Object}
-   */
-  serialize() {
-    return {
-      state: this._state,
-      history: this._historyEnabled ? this._history : undefined,
-      metadata: Object.keys(this._metadata).length > 0 ? this._metadata : undefined,
-    };
-  }
-
-  /**
-   * Deserialize state machine
-   * @param {Object} data - Serialized data
-   * @param {Object} [options={}] - Options
-   * @returns {SessionStateMachine}
-   */
-  static deserialize(data, options = {}) {
-    const sm = new SessionStateMachine(data.state, {
-      ...options,
-      historyEnabled: !!data.history,
-    });
-
-    if (data.history) {
-      sm._history = data.history.map(h => ({
-        ...h,
-        timestamp: new Date(h.timestamp),
-      }));
-    }
-
-    if (data.metadata) {
-      sm._metadata = data.metadata;
-    }
-
-    return sm;
-  }
-
-  /**
-   * Create state machine diagram (Mermaid format)
-   * @returns {string}
-   */
-  static toMermaid() {
-    const lines = ['stateDiagram-v2'];
-
-    for (const [state, transitions] of Object.entries(TRANSITIONS)) {
-      for (const [action, nextState] of Object.entries(transitions)) {
-        lines.push(`    ${state} --> ${nextState}: ${action}`);
-      }
-    }
-
-    // Mark initial and final states
-    lines.push('    [*] --> idle');
-    lines.push('    terminated --> [*]');
-
-    return lines.join('\n');
-  }
-}
-
-/**
- * Create a pre-configured state machine for sessions
- * @param {Object} [options={}] - Options
- * @returns {SessionStateMachine}
- */
-function createSessionStateMachine(options = {}) {
-  return new SessionStateMachine(SessionState.IDLE, options);
-}
-
-module.exports = {
-  // Enums
-  SessionState,
-  SessionAction,
-
-  // Constants
-  TRANSITIONS,
-
-  // Utility functions
-  getValidStates,
-  getValidActions,
-  isValidState,
-  isValidAction,
-  getTransitionsFromState,
-  getAvailableActions,
-  canTransition,
-  getNextState,
-
-  // Classes
-  StateMachineError,
-  SessionStateMachine,
-
-  // Factory
-  createSessionStateMachine,
-};

package/lib/session-switching.js

@@ -1,191 +0,0 @@
-/**
- * session-switching.js - Session switching and thread type management
- *
- * Extracted from session-manager.js to reduce file size.
- * Uses factory pattern for dependency injection.
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const { getSessionStatePath } = require('./paths');
-const { sessionThreadMachine } = require('./state-machine');
-const { THREAD_TYPES } = require('./worktree-operations');
-
-/**
- * Create session switching operations bound to the given dependencies.
- *
- * @param {object} deps
- * @param {string} deps.ROOT - Project root path
- * @param {Function} deps.loadRegistry - Load registry data
- * @param {Function} deps.saveRegistry - Save registry data
- */
-function createSessionSwitching(deps) {
-  const { ROOT, loadRegistry, saveRegistry } = deps;
-
-  const SESSION_STATE_PATH = getSessionStatePath(ROOT);
-
-  // ============================================================================
-  // Session Switching
-  // ============================================================================
-
-  function switchSession(sessionIdOrNickname) {
-    const registry = loadRegistry();
-    let targetSession = null,
-      targetId = null;
-    for (const [id, session] of Object.entries(registry.sessions)) {
-      if (id === sessionIdOrNickname || session.nickname === sessionIdOrNickname) {
-        targetSession = session;
-        targetId = id;
-        break;
-      }
-    }
-    if (!targetSession)
-      return { success: false, error: `Session "${sessionIdOrNickname}" not found` };
-    if (!fs.existsSync(targetSession.path))
-      return { success: false, error: `Session directory does not exist: ${targetSession.path}` };
-
-    let sessionState = {};
-    if (fs.existsSync(SESSION_STATE_PATH)) {
-      try {
-        sessionState = JSON.parse(fs.readFileSync(SESSION_STATE_PATH, 'utf8'));
-      } catch (e) {
-        /* start fresh */
-      }
-    }
-
-    sessionState.active_session = {
-      id: targetId,
-      nickname: targetSession.nickname,
-      path: targetSession.path,
-      branch: targetSession.branch,
-      switched_at: new Date().toISOString(),
-      original_cwd: ROOT,
-    };
-
-    const stateDir = path.dirname(SESSION_STATE_PATH);
-    if (!fs.existsSync(stateDir)) fs.mkdirSync(stateDir, { recursive: true });
-    fs.writeFileSync(SESSION_STATE_PATH, JSON.stringify(sessionState, null, 2) + '\n');
-
-    registry.sessions[targetId].last_active = new Date().toISOString();
-    saveRegistry(registry);
-
-    return {
-      success: true,
-      session: {
-        id: targetId,
-        nickname: targetSession.nickname,
-        path: targetSession.path,
-        branch: targetSession.branch,
-      },
-      path: targetSession.path,
-      addDirCommand: `/add-dir ${targetSession.path}`,
-    };
-  }
-
-  function clearActiveSession() {
-    if (!fs.existsSync(SESSION_STATE_PATH)) return { success: true };
-    try {
-      const sessionState = JSON.parse(fs.readFileSync(SESSION_STATE_PATH, 'utf8'));
-      delete sessionState.active_session;
-      fs.writeFileSync(SESSION_STATE_PATH, JSON.stringify(sessionState, null, 2) + '\n');
-      return { success: true };
-    } catch (e) {
-      return { success: false, error: e.message };
-    }
-  }
-
-  function getActiveSession() {
-    if (!fs.existsSync(SESSION_STATE_PATH)) return { active: false };
-    try {
-      const sessionState = JSON.parse(fs.readFileSync(SESSION_STATE_PATH, 'utf8'));
-      return sessionState.active_session
-        ? { active: true, session: sessionState.active_session }
-        : { active: false };
-    } catch (e) {
-      return { active: false };
-    }
-  }
-
-  // ============================================================================
-  // Thread Type Management
-  // ============================================================================
-
-  function getSessionThreadType(sessionId = null) {
-    const registry = loadRegistry();
-    const cwd = process.cwd();
-    let targetId = sessionId;
-    if (!targetId) {
-      for (const [id, session] of Object.entries(registry.sessions)) {
-        if (session.path === cwd) {
-          targetId = id;
-          break;
-        }
-      }
-    }
-    if (!targetId || !registry.sessions[targetId])
-      return { success: false, error: 'Session not found' };
-    const session = registry.sessions[targetId];
-    const threadType = session.thread_type || (session.is_main ? 'base' : 'parallel');
-    return {
-      success: true,
-      thread_type: threadType,
-      session_id: targetId,
-      is_main: session.is_main,
-    };
-  }
-
-  function setSessionThreadType(sessionId, threadType) {
-    if (!THREAD_TYPES.includes(threadType)) {
-      return {
-        success: false,
-        error: `Invalid thread type: ${threadType}. Valid: ${THREAD_TYPES.join(', ')}`,
-      };
-    }
-    const registry = loadRegistry();
-    if (!registry.sessions[sessionId])
-      return { success: false, error: `Session ${sessionId} not found` };
-    registry.sessions[sessionId].thread_type = threadType;
-    saveRegistry(registry);
-    return { success: true, thread_type: threadType };
-  }
-
-  function transitionThread(sessionId, targetType, options = {}) {
-    const { force = false } = options;
-    const registry = loadRegistry();
-    const session = registry.sessions[sessionId];
-    if (!session) return { success: false, error: `Session ${sessionId} not found` };
-
-    const currentType = session.thread_type || (session.is_main ? 'base' : 'parallel');
-    const result = sessionThreadMachine.transition(currentType, targetType, { force });
-    if (!result.success)
-      return { success: false, from: currentType, to: targetType, error: result.error };
-    if (result.noop) return { success: true, from: currentType, to: targetType, noop: true };
-
-    registry.sessions[sessionId].thread_type = targetType;
-    registry.sessions[sessionId].thread_transitioned_at = new Date().toISOString();
-    saveRegistry(registry);
-    return { success: true, from: currentType, to: targetType, forced: result.forced || false };
-  }
-
-  function getValidThreadTransitions(sessionId) {
-    const registry = loadRegistry();
-    const session = registry.sessions[sessionId];
-    if (!session) return { success: false, error: `Session ${sessionId} not found` };
-    const currentType = session.thread_type || (session.is_main ? 'base' : 'parallel');
-    const validTransitions = sessionThreadMachine.getValidTransitions(currentType);
-    return { success: true, current: currentType, validTransitions };
-  }
-
-  return {
-    switchSession,
-    clearActiveSession,
-    getActiveSession,
-    getSessionThreadType,
-    setSessionThreadType,
-    transitionThread,
-    getValidThreadTransitions,
-  };
-}
-
-module.exports = { createSessionSwitching };