Actions System Documentation¶

┌─────────────────────────────────────────────────────────────┐
│                    Actions System                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────────┐        ┌──────────────────┐         │
│  │  ActionManager   │◄──────►│ CheckpointManager│         │
│  │  (Legacy)        │        │                  │         │
│  └────────┬─────────┘        └──────────────────┘         │
│           │                                                 │
│           │  Evolution                                      │
│           ▼                                                 │
│  ┌──────────────────┐        ┌──────────────────┐         │
│  │ModernActionMgr   │◄──────►│   ActionTools    │         │
│  │  (Command-based) │        │   (MCP Server)   │         │
│  └──────────────────┘        └──────────────────┘         │
│                                                             │
│  ┌─────────────────────────────────────────────┐          │
│  │         Tool Registry (YAML)                │          │
│  │  • copy_sequence.yaml                       │          │
│  │  • paste_sequence.yaml                      │          │
│  │  • delete_sequence.yaml                     │          │
│  │  • insert_sequence.yaml                     │          │
│  │  • replace_sequence.yaml                    │          │
│  └─────────────────────────────────────────────┘          │
└─────────────────────────────────────────────────────────────┘

src/
├── renderer/modules/
│   ├── ActionManager.js              # Main implementation (5918 lines)
│   └── CheckpointManager.js          # State backup/restore (1130 lines)
├── mcp-tools/action/
│   └── ActionTools.js                # MCP server integration (313 lines)
└── temp/modern/
    └── ModernActionManager.js        # Modern command-based version (812 lines)

tools_registry/sequence_editing/
├── copy_sequence.yaml                # Copy action definition
├── cut_sequence.yaml                 # Cut action definition
├── paste_sequence.yaml               # Paste action definition
├── delete_sequence.yaml              # Delete action definition
├── insert_sequence.yaml              # Insert action definition
├── replace_sequence.yaml             # Replace action definition
├── execute_actions.yaml              # Execute queue definition
├── get_action_list.yaml              # List actions definition
├── clear_actions.yaml                # Clear queue definition
└── undo_last_action.yaml             # Undo definition

{
    actions: [],              // Action queue
    clipboard: null,          // Clipboard data
    cursorPosition: 0,        // DEPRECATED: Cursor position
    sequenceModifications: Map, // Track modifications per chromosome
    originalAnnotations: null,  // Backup for rollback
    isExecuting: false,       // Execution lock
    nextActionId: 1           // Auto-increment ID
}

ACTION_TYPES = {
  COPY_SEQUENCE: 'copy_sequence',
  CUT_SEQUENCE: 'cut_sequence',
  PASTE_SEQUENCE: 'paste_sequence',
  DELETE_SEQUENCE: 'delete_sequence',
  INSERT_SEQUENCE: 'insert_sequence',
  REPLACE_SEQUENCE: 'replace_sequence',
  SEQUENCE_EDIT: 'sequence_edit',
};

STATUS = {
  PENDING: 'pending',
  EXECUTING: 'executing',
  COMPLETED: 'completed',
  FAILED: 'failed',
};

Commands = {
    'action:setCursorPosition',  // Set cursor
    'action:paste',              // Paste sequence
    'action:delete',             // Delete sequence
    'action:copy',               // Copy sequence
    'action:executeAll'          // Execute queue
}

CHECKPOINT_TYPES = {
  MANUAL: 'manual',
  AUTO: 'auto',
  BEFORE_ACTION: 'before_action',
  MILESTONE: 'milestone',
};

chromosome: string # Chromosome identifier
start: number # Start position (1-based)
end: number # End position (1-based)
strand: string # "+" or "-"
include_annotations: boolean # Include features

actionManager.addAction('copy_sequence', 'chr1:1000-2000(+)', 'Copy 1000 bp region', {
  chromosome: 'chr1',
  start: 1000,
  end: 2000,
  strand: '+',
});

chromosome: string
position: number # Insert position
start: number # Or replacement start
end: number # Replacement end

chromosome: string
start: number
end: number
strand: string

chromosome: string
position: number
sequence: string # DNA sequence (ATGCN)

chromosome: string
start: number
end: number
sequence: string
strand: string

┌─────────────┐
│   Create    │
│   Action    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Add to     │◄─── User Input / API Call
│   Queue     │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Validate   │
│  & Check    │
│  Conflicts  │
└──────┬──────┘
       │
       ├─── Conflicts? ──► User Decision
       │                       │
       ▼                       │
┌─────────────┐               │
│  Execute    │◄──────────────┘
│   Queue     │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Update     │
│  Features   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Generate   │
│  GBK File   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Done      │
└─────────────┘

for each pending action:
    - Execute on copy
    - Update features
    - Adjust remaining actions
    - Update progress

// Create and add action
addAction(type, target, details, metadata) → actionId

// Create action without adding
createAction(type, target, details, metadata) → action

// Remove action from queue
removeAction(actionId) → boolean

// Clear all or filtered actions
clearAllActions(status = 'all') → void

// Get action by ID
getAction(actionId) → action

// Execute all pending actions
executeAllActions() → Promise<result>

// Execute single action
executeSingleAction(actionId) → Promise<result>

// Check for conflicts
checkActionConflicts(pendingActions) → conflictAnalysis

// Handle copy
handleCopySequence() → Promise<void>

// Handle cut
handleCutSequence() → Promise<void>

// Handle paste
handlePasteSequence() → Promise<void>

// Handle delete
handleDeleteSequence() → Promise<void>

// Get clipboard content
getClipboardContent() → clipboardData

// Get active selection (prioritized)
getActiveSelection() → selectionInfo

// Set cursor position (DEPRECATED)
setCursorPosition(position) → void

// Get sequence for region
getSequenceForRegion(chr, start, end, strand) → Promise<sequence>

// Collect comprehensive data
collectComprehensiveData(chr, start, end, strand) → Promise<data>

// Adjust feature positions
adjustFeaturePositions(chr, features) → features

// Update features after action
updateAllFeaturesAfterAction(action, genomeData) → Promise<void>

// Generate GBK file
generateComprehensiveGBK(actions, genomeData, execId) → Promise<void>

// Generate chromosome GBK
generateChromosomeGBKContentOriginal(chr, seq, features, actions, execId) → string

// Show action list
showActionList() → void

// Update action list UI
updateActionListUI() → void

// Show sequence selection modal
showSequenceSelectionModal(operation) → void

// Function execution
executeActionFunction(functionName, parameters) → Promise<result>

// Individual functions
functionCopySequence(params) → Promise<result>
functionCutSequence(params) → Promise<result>
functionPasteSequence(params) → Promise<result>
functionDeleteSequence(params) → Promise<result>
functionInsertSequence(params) → Promise<result>
functionReplaceSequence(params) → Promise<result>
functionGetActionList(params) → result
functionExecuteActions(params) → Promise<result>
functionClearActions(params) → result
functionUndoLastAction(params) → Promise<result>
functionGetClipboardContent(params) → result
functionOpenNewTab(params) → Promise<result>
functionSwitchToTab(params) → Promise<result>

// Execute command
context.execute(commandName, params) → Promise<result>

// Available commands:
// - action:setCursorPosition
// - action:paste
// - action:delete
// - action:copy
// - action:executeAll

// Get status
getActionStatus() → status

// Get metrics
getMetrics() → metrics

// Cleanup
destroy() → void

this.cursorPosition = 0; // DEPRECATED but still in use
setCursorPosition(position); // DEPRECATED but public API

// Sometimes throws
throw new Error('...');

// Sometimes returns false
return false;

// Sometimes shows notification
this.showNotification('...', 'error');

this.genomeBrowser.showNotification(...)
this.genomeBrowser.currentSequence[...]

const executionGenomeData = JSON.parse(JSON.stringify(originalGenomeData));

const executionGenomeData = this.createGenomeDataCopy(originalGenomeData);

// Use structural sharing
class GenomeDataProxy {
  constructor(original) {
    this.original = original;
    this.modifications = new Map();
  }

  getSequence(chr) {
    return this.modifications.has(chr) ? this.modifications.get(chr) : this.original.sequence[chr];
  }

  modifySequence(chr, newSeq) {
    this.modifications.set(chr, newSeq);
  }
}

ActionManager/
├── core/
│   ├── ActionQueue.js       # Queue management
│   ├── ActionExecutor.js    # Execution logic
│   └── ActionValidator.js   # Validation & conflicts
├── operations/
│   ├── CopyOperation.js
│   ├── PasteOperation.js
│   └── DeleteOperation.js
├── features/
│   ├── FeatureAdjuster.js
│   └── FeatureTracker.js
├── export/
│   └── GenbankExporter.js
└── ui/
    ├── ActionListUI.js
    └── ActionModals.js

/**
 * Add action to queue
 * @param {ActionType} type - Action type constant
 * @param {string} target - Target location (chr:start-end)
 * @param {string} details - Human-readable description
 * @param {ActionMetadata} metadata - Action metadata
 * @returns {number} Action ID
 */
addAction(type, target, details, metadata = {}) {
    // ...
}

/**
 * @typedef {Object} ActionMetadata
 * @property {string} chromosome - Chromosome identifier
 * @property {number} start - Start position (1-based)
 * @property {number} end - End position (1-based)
 * @property {string} [strand='+'] - Strand direction
 * @property {*} [clipboardData] - Clipboard content for paste
 */

class ActionError extends Error {
    constructor(message, code, details = {}) {
        super(message);
        this.name = 'ActionError';
        this.code = code;
        this.details = details;
    }
}

class ActionValidationError extends ActionError {
    constructor(message, details) {
        super(message, 'VALIDATION_ERROR', details);
    }
}

// Usage
async executeAllActions() {
    try {
        // ...
    } catch (error) {
        if (error instanceof ActionValidationError) {
            this.showNotification(error.message, 'warning');
        } else if (error instanceof ActionError) {
            this.showNotification(error.message, 'error');
        } else {
            console.error('Unexpected error:', error);
            throw error;
        }
    }
}

class ActionManager {
  constructor(dependencies) {
    this.notifier = dependencies.notifier;
    this.sequenceProvider = dependencies.sequenceProvider;
    this.featureProvider = dependencies.featureProvider;
    this.eventBus = dependencies.eventBus;
  }

  showNotification(message, type) {
    this.notifier.show(message, type);
  }

  getCurrentSequence(chr) {
    return this.sequenceProvider.getSequence(chr);
  }
}

// Usage
const actionManager = new ActionManager({
  notifier: genomeBrowser.notificationService,
  sequenceProvider: genomeBrowser.sequenceService,
  featureProvider: genomeBrowser.featureService,
  eventBus: genomeBrowser.eventBus,
});

class ActionState {
  constructor() {
    this.state = {
      queue: [],
      clipboard: null,
      isExecuting: false,
      modifications: new Map(),
      originalAnnotations: null,
    };
    this.listeners = new Set();
  }

  dispatch(action) {
    const newState = this.reducer(this.state, action);
    if (newState !== this.state) {
      this.state = newState;
      this.notify();
    }
  }

  reducer(state, action) {
    switch (action.type) {
      case 'ADD_ACTION':
        return {
          ...state,
          queue: [...state.queue, action.payload],
        };
      case 'SET_CLIPBOARD':
        return {
          ...state,
          clipboard: action.payload,
        };
      // ... more cases
      default:
        return state;
    }
  }

  subscribe(listener) {
    this.listeners.add(listener);
    return () => this.listeners.delete(listener);
  }

  notify() {
    this.listeners.forEach(listener => listener(this.state));
  }
}

/**
 * Collect comprehensive genomic data for a region including sequence,
 * features, variants, and reads. Creates deep copies to prevent
 * reference issues during action execution.
 *
 * @param {string} chromosome - Chromosome identifier
 * @param {number} start - Start position (1-based, inclusive)
 * @param {number} end - End position (1-based, inclusive)
 * @param {string} strand - Strand direction ('+' or '-')
 * @param {Object} [executionGenomeData=null] - Optional execution copy to use
 * @returns {Promise<ComprehensiveData>} Comprehensive region data
 *
 * @typedef {Object} ComprehensiveData
 * @property {RegionInfo} region - Region metadata
 * @property {Feature[]} features - Overlapping features
 * @property {Variant[]} variants - Overlapping variants
 * @property {Read[]} reads - Overlapping reads
 * @property {Object} metadata - Calculated metadata (GC%, types, counts)
 *
 * @example
 * const data = await collectComprehensiveData('chr1', 1000, 2000, '+');
 * console.log(`Found ${data.features.length} features`);
 */
async collectComprehensiveData(chromosome, start, end, strand, executionGenomeData = null) {
    // ...
}

// tests/ActionManager.test.js
describe('ActionManager', () => {
  let actionManager;
  let mockGenomeBrowser;

  beforeEach(() => {
    mockGenomeBrowser = createMockGenomeBrowser();
    actionManager = new ActionManager(mockGenomeBrowser);
  });

  describe('addAction', () => {
    it('should add action to queue', () => {
      const actionId = actionManager.addAction('copy_sequence', 'chr1:1000-2000(+)', 'Test copy', {
        chromosome: 'chr1',
        start: 1000,
        end: 2000,
      });

      expect(actionManager.actions).toHaveLength(1);
      expect(actionManager.actions[0].id).toBe(actionId);
    });

    it('should validate action parameters', () => {
      expect(() => {
        actionManager.addAction(
          'copy_sequence',
          'chr1:2000-1000(+)', // Invalid: start > end
          'Invalid copy',
          { chromosome: 'chr1', start: 2000, end: 1000 }
        );
      }).toThrow(ActionValidationError);
    });
  });

  describe('executeAllActions', () => {
    it('should execute pending actions in order', async () => {
      // ... test implementation
    });

    it('should detect conflicts', async () => {
      // ... test implementation
    });

    it('should rollback on error', async () => {
      // ... test implementation
    });
  });
});

// ✅ GOOD: Use metadata for structured data
actionManager.addAction(actionManager.ACTION_TYPES.COPY_SEQUENCE, 'chr1:1000-2000(+)', 'Copy promoter region', {
  chromosome: 'chr1',
  start: 1000,
  end: 2000,
  strand: '+',
  feature: 'promoter',
  reason: 'analysis',
});

// ❌ BAD: Unstructured details
actionManager.addAction('copy', 'somewhere', 'copy some stuff', {});

// ✅ GOOD: Try-catch with specific errors
try {
  await actionManager.executeAllActions();
} catch (error) {
  if (error instanceof ActionValidationError) {
    console.warn('Validation failed:', error.details);
    // Show user-friendly message
  } else {
    console.error('Unexpected error:', error);
    // Log to error tracking service
  }
}

// ❌ BAD: Silent failures
actionManager.executeAllActions().catch(() => {});

// ✅ GOOD: Use execution genome data copy
const executionGenomeData = this.createGenomeDataCopy(originalData);
await this.executeActionOnCopy(action, executionGenomeData);
await this.updateAllFeaturesAfterAction(action, executionGenomeData);

// ❌ BAD: Modify original data directly
this.genomeBrowser.currentAnnotations[chr] = modifiedFeatures;

// ✅ GOOD: Immutable updates
this.actions = [...this.actions, newAction];

// ❌ BAD: Direct mutation
this.actions.push(newAction);

// ✅ GOOD: Include comprehensive data
this.clipboard = {
    type: 'copy',
    sequence: sequenceData,
    source: target,
    timestamp: new Date(),
    comprehensiveData: await this.collectComprehensiveData(...)
};

// ❌ BAD: Minimal clipboard data
this.clipboard = sequenceData;

// ✅ GOOD: Batch UI updates
this.updateActionListUI();
this.updateStats();
this.notifyActionsTrackUpdate();

// ❌ BAD: Multiple redundant updates in loop
for (const action of actions) {
  this.updateUI(); // Called every iteration
}

// OLD
const actionManager = new ActionManager(genomeBrowser);

// NEW
const context = new ApplicationContext();
const actionManager = new ModernActionManager(context);

// OLD
actionManager.handlePasteSequence();

// NEW
await context.execute('action:paste', { position: 1000 });

// OLD
actionManager.addEventListener('actionComplete', handler);

// NEW
context.getService('eventBus').on('action:queued', handler);

{
    id: number,              // Unique identifier
    type: string,            // ACTION_TYPES constant
    target: string,          // "chr:start-end(strand)"
    details: string,         // Human-readable description
    metadata: {              // Action-specific data
        chromosome: string,
        start: number,
        end: number,
        strand: string,
        ...                  // Type-specific fields
    },
    status: string,          // STATUS constant
    timestamp: Date,         // Creation time
    estimatedTime: number,   // Estimated execution time (ms)
    result: object | null,   // Execution result
    error: string | null,    // Error message if failed
    executionStart: Date,    // Execution start time
    executionEnd: Date,      // Execution end time
    actualTime: number       // Actual execution time (ms)
}

{
    type: 'copy' | 'cut',           // Operation type
    sequence: string,                // DNA sequence
    source: string,                  // Source location
    timestamp: Date,                 // Copy/cut time
    sourceInfo: {                    // Source selection info
        chromosome: string,
        start: number,
        end: number,
        strand: string,
        source: string,              // 'manual' | 'gene' | 'selectedGene'
        name: string
    },
    comprehensiveData: {             // Full region data
        region: object,
        features: array,
        variants: array,
        reads: array,
        metadata: object
    }
}

{
    hasConflicts: boolean,
    conflicts: [
        {
            type: 'position_overlap',
            chromosome: string,
            action1: object,
            action2: object,
            overlapStart: number,
            overlapEnd: number,
            severity: 'high' | 'medium' | 'low',
            description: string
        }
    ],
    totalActions: number,
    affectedChromosomes: string[]
}