@agile-vibe-coding/avc 0.1.0 → 0.2.3

package/cli/message-manager.js

@@ -0,0 +1,334 @@
+/**
+ * MessageManager - Centralized message handling system
+ *
+ * Singleton that manages all console output through execution contexts.
+ * Prevents ghost messages by tracking command lifecycle and cancelling
+ * messages from previous runs.
+ */
+
+import { MessageType } from './message-types.js';
+import { ExecutionContext } from './execution-context.js';
+import { outputBuffer } from './output-buffer.js';
+
+/**
+ * MessageManager singleton class
+ */
+class MessageManager {
+  constructor() {
+    if (MessageManager.instance) {
+      return MessageManager.instance;
+    }
+
+    this.currentContext = null;
+    this.contextHistory = [];
+    this.maxHistorySize = 10;
+    this.executingMessageCallback = null;
+    this.executingSubstepCallback = null;
+
+    MessageManager.instance = this;
+  }
+
+  /**
+   * Set executing message callback (from React state setter)
+   * @param {Function} callback - setExecutingMessage function
+   */
+  setExecutingMessageCallback(callback) {
+    this.executingMessageCallback = callback;
+  }
+
+  /**
+   * Set executing substep callback (from React state setter)
+   * @param {Function} callback - setExecutingSubstep function
+   */
+  setExecutingSubstepCallback(callback) {
+    this.executingSubstepCallback = callback;
+  }
+
+  /**
+   * Start a new execution context for a command
+   * @param {string} commandName - Name of the command
+   * @returns {ExecutionContext} New execution context
+   */
+  startExecution(commandName) {
+    // Cancel previous context if active
+    if (this.currentContext && this.currentContext.isActive()) {
+      this.currentContext.cancel();
+    }
+
+    // Create new context
+    this.currentContext = new ExecutionContext(commandName);
+
+    // Add to history
+    this.contextHistory.push(this.currentContext);
+    if (this.contextHistory.length > this.maxHistorySize) {
+      this.contextHistory.shift();
+    }
+
+    // Insert visual separator between commands in the Static output
+    outputBuffer.clear();
+
+    return this.currentContext;
+  }
+
+  /**
+   * End the current execution context
+   */
+  endExecution() {
+    if (this.currentContext) {
+      this.currentContext.complete();
+      this.currentContext = null;
+    }
+
+    // Clear progress indicators
+    if (this.executingMessageCallback) {
+      this.executingMessageCallback('');
+    }
+    if (this.executingSubstepCallback) {
+      this.executingSubstepCallback('');
+    }
+  }
+
+  /**
+   * Cancel the current execution context
+   */
+  cancelExecution() {
+    if (this.currentContext) {
+      this.currentContext.cancel();
+      this.currentContext = null;
+    }
+
+    // Clear progress indicators
+    if (this.executingMessageCallback) {
+      this.executingMessageCallback('');
+    }
+    if (this.executingSubstepCallback) {
+      this.executingSubstepCallback('');
+    }
+  }
+
+  /**
+   * Get current execution context
+   * @returns {ExecutionContext|null} Current context or null
+   */
+  getCurrentContext() {
+    return this.currentContext;
+  }
+
+  /**
+   * Send a message through the current context
+   * @param {string} type - MessageType
+   * @param {string} content - Message content
+   * @param {Object} options - Additional options
+   */
+  send(type, content, options = {}) {
+    // Validate message type
+    if (!Object.values(MessageType).includes(type)) {
+      console.error(`Invalid message type: ${type}`);
+      return;
+    }
+
+    // Ignore if no active context
+    if (!this.currentContext || !this.currentContext.isActive()) {
+      return;
+    }
+
+    // Handle different message types
+    switch (type) {
+      case MessageType.COMMAND_START:
+        this._handleCommandStart(content);
+        break;
+
+      case MessageType.CEREMONY_HEADER:
+        this._handleCeremonyHeader(content);
+        break;
+
+      case MessageType.PROGRESS:
+        this._handleProgress(content);
+        break;
+
+      case MessageType.SUBSTEP:
+        this._handleSubstep(content);
+        break;
+
+      case MessageType.USER_OUTPUT:
+        this._handleUserOutput(content);
+        break;
+
+      case MessageType.ERROR:
+        this._handleError(content);
+        break;
+
+      case MessageType.WARNING:
+        this._handleWarning(content);
+        break;
+
+      case MessageType.SUCCESS:
+        this._handleSuccess(content);
+        break;
+
+      case MessageType.INFO:
+        this._handleInfo(content);
+        break;
+
+      case MessageType.DEBUG:
+        this._handleDebug(content, options);
+        break;
+
+      default:
+        this._handleUserOutput(content);
+    }
+  }
+
+  /**
+   * Handle COMMAND_START message
+   * @private
+   */
+  _handleCommandStart(content) {
+    // Clear output buffer (already done in startExecution)
+    // This is a marker message type, no output needed
+  }
+
+  /**
+   * Handle CEREMONY_HEADER message
+   * @private
+   */
+  _handleCeremonyHeader(content) {
+    outputBuffer.append(content);
+  }
+
+  /**
+   * Handle PROGRESS message
+   * @private
+   */
+  _handleProgress(content) {
+    if (this.currentContext) {
+      this.currentContext.setExecutingMessage(content);
+    }
+    if (this.executingMessageCallback) {
+      this.executingMessageCallback(content);
+    }
+  }
+
+  /**
+   * Handle SUBSTEP message
+   * @private
+   */
+  _handleSubstep(content) {
+    if (this.currentContext) {
+      this.currentContext.setExecutingSubstep(content);
+    }
+    if (this.executingSubstepCallback) {
+      this.executingSubstepCallback(content);
+    }
+  }
+
+  /**
+   * Handle USER_OUTPUT message
+   * @private
+   */
+  _handleUserOutput(content) {
+    // Empty string means "blank line" — outputBuffer ignores falsy values,
+    // so convert '' to '\n' to produce the intended visual gap.
+    outputBuffer.append(content === '' ? '\n' : content);
+  }
+
+  /**
+   * Handle ERROR message
+   * @private
+   */
+  _handleError(content) {
+    outputBuffer.append(`ERROR: ${content}`, 'ERROR');
+  }
+
+  /**
+   * Handle WARNING message
+   * @private
+   */
+  _handleWarning(content) {
+    outputBuffer.append(`WARNING: ${content}`, 'WARNING');
+  }
+
+  /**
+   * Handle SUCCESS message
+   * @private
+   */
+  _handleSuccess(content) {
+    outputBuffer.append(`SUCCESS: ${content}`, 'SUCCESS');
+  }
+
+  /**
+   * Handle INFO message
+   * @private
+   */
+  _handleInfo(content) {
+    outputBuffer.append(`INFO: ${content}`, 'INFO');
+  }
+
+  /**
+   * Handle DEBUG message
+   * @private
+   */
+  _handleDebug(content, options = {}) {
+    // Debug messages only go to console.log, not main output
+    const timestamp = new Date().toISOString();
+    if (options.data) {
+      console.log(`[DEBUG][${timestamp}] ${content}`, JSON.stringify(options.data, null, 2));
+    } else {
+      console.log(`[DEBUG][${timestamp}] ${content}`);
+    }
+  }
+
+  /**
+   * Clear progress indicators
+   */
+  clearProgress() {
+    if (this.currentContext) {
+      this.currentContext.clearExecutingMessage();
+      this.currentContext.clearExecutingSubstep();
+    }
+    if (this.executingMessageCallback) {
+      this.executingMessageCallback('');
+    }
+    if (this.executingSubstepCallback) {
+      this.executingSubstepCallback('');
+    }
+  }
+
+  /**
+   * Get execution context history
+   * @returns {Array} Array of execution contexts
+   */
+  getHistory() {
+    return [...this.contextHistory];
+  }
+
+  /**
+   * Get manager state for debugging
+   * @returns {Object} Manager state
+   */
+  toJSON() {
+    return {
+      hasCurrentContext: !!this.currentContext,
+      currentContext: this.currentContext ? this.currentContext.toJSON() : null,
+      historySize: this.contextHistory.length,
+      hasCallbacks: {
+        executingMessage: !!this.executingMessageCallback,
+        executingSubstep: !!this.executingSubstepCallback
+      }
+    };
+  }
+
+  /**
+   * Reset manager (for testing)
+   */
+  reset() {
+    if (this.currentContext) {
+      this.currentContext.cancel();
+    }
+    this.currentContext = null;
+    this.contextHistory = [];
+  }
+}
+
+// Export singleton instance
+export const messageManager = new MessageManager();

package/cli/message-types.js

@@ -0,0 +1,96 @@
+/**
+ * Message Types for MessageManager
+ *
+ * Defines different types of messages that can be sent through the messaging system.
+ * Each type can be handled differently (formatting, logging, display).
+ */
+
+export const MessageType = {
+  /**
+   * Command start - marks the beginning of a command execution
+   * Typically clears the output buffer
+   */
+  COMMAND_START: 'COMMAND_START',
+
+  /**
+   * Ceremony header - displays ceremony title and documentation URL
+   * Format: 🎯 Title\n📖 URL
+   */
+  CEREMONY_HEADER: 'CEREMONY_HEADER',
+
+  /**
+   * Progress indicator - shows ongoing operation status
+   * These go to executingMessage state, not main output
+   */
+  PROGRESS: 'PROGRESS',
+
+  /**
+   * Substep progress - shows detailed progress within an operation
+   * These go to executingSubstep state, not main output
+   */
+  SUBSTEP: 'SUBSTEP',
+
+  /**
+   * User output - main content shown to user
+   * Standard output messages
+   */
+  USER_OUTPUT: 'USER_OUTPUT',
+
+  /**
+   * Error message - displays errors to user
+   * Automatically formatted with ERROR: prefix in red bold
+   */
+  ERROR: 'ERROR',
+
+  /**
+   * Warning message - displays warnings to user
+   * Automatically formatted with WARNING: prefix in yellow bold
+   */
+  WARNING: 'WARNING',
+
+  /**
+   * Success message - displays success confirmation
+   * Automatically formatted with SUCCESS: prefix in green bold
+   */
+  SUCCESS: 'SUCCESS',
+
+  /**
+   * Debug message - development/troubleshooting info
+   * Not shown in main output, only console.log
+   */
+  DEBUG: 'DEBUG',
+
+  /**
+   * Info message - informational content
+   * Automatically formatted with INFO: prefix in cyan
+   */
+  INFO: 'INFO'
+};
+
+/**
+ * Check if a message type is valid
+ * @param {string} type - Message type to validate
+ * @returns {boolean} True if valid
+ */
+export function isValidMessageType(type) {
+  return Object.values(MessageType).includes(type);
+}
+
+/**
+ * Get default formatting for a message type
+ * @param {string} type - Message type
+ * @returns {object} Format configuration with prefix, color, and bold flag
+ */
+export function getMessageFormat(type) {
+  const formats = {
+    [MessageType.ERROR]: { prefix: 'ERROR: ', color: 'red', bold: true },
+    [MessageType.WARNING]: { prefix: 'WARNING: ', color: 'yellow', bold: true },
+    [MessageType.SUCCESS]: { prefix: 'SUCCESS: ', color: 'green', bold: true },
+    [MessageType.INFO]: { prefix: 'INFO: ', color: 'cyan', bold: false },
+    [MessageType.CEREMONY_HEADER]: { prefix: '', color: 'cyan', bold: true },
+    [MessageType.USER_OUTPUT]: { prefix: '', color: 'white', bold: false },
+    [MessageType.DEBUG]: { prefix: '[DEBUG] ', color: 'gray', bold: false }
+  };
+
+  return formats[type] || { prefix: '', color: 'white', bold: false };
+}

package/cli/messaging-api.js

@@ -0,0 +1,297 @@
+/**
+ * Messaging API - Simple interface for command message handling
+ *
+ * Provides convenient methods for commands to send messages through
+ * the MessageManager without directly importing it.
+ */
+
+import { messageManager } from './message-manager.js';
+import { MessageType } from './message-types.js';
+import { boldCyan, gray, cyan } from './ansi-colors.js';
+
+/**
+ * Track sent ceremony headers to prevent duplication
+ * Cleared on each startCommand() call
+ */
+let ceremonySent = new Set();
+
+/**
+ * Start a new command execution context
+ * Should be called at the beginning of every command
+ *
+ * @param {string} commandName - Name of the command (e.g., 'sponsor-call')
+ * @returns {ExecutionContext} New execution context
+ *
+ * @example
+ * import { startCommand, endCommand } from './messaging-api.js';
+ *
+ * async function sponsorCallCommand() {
+ *   startCommand('sponsor-call');
+ *   try {
+ *     // ... command logic
+ *   } finally {
+ *     endCommand();
+ *   }
+ * }
+ */
+export function startCommand(commandName) {
+  // Clear ceremony header tracking for new command
+  ceremonySent.clear();
+  return messageManager.startExecution(commandName);
+}
+
+/**
+ * End the current command execution context
+ * Should be called in finally block to ensure cleanup
+ *
+ * @example
+ * try {
+ *   // ... command logic
+ * } finally {
+ *   endCommand();
+ * }
+ */
+export function endCommand() {
+  messageManager.endExecution();
+}
+
+/**
+ * Cancel the current command execution context
+ * Used when user interrupts or restarts command
+ */
+export function cancelCommand() {
+  messageManager.cancelExecution();
+}
+
+/**
+ * Send a ceremony header (title + documentation URL)
+ * Automatically prevents duplicate headers within same command execution
+ *
+ * @param {string} title - Ceremony title (without emoji)
+ * @param {string} url - Documentation URL
+ *
+ * @example
+ * sendCeremonyHeader('Sponsor Call Ceremony', 'https://agilevibecoding.org/ceremonies/sponsor-call');
+ */
+export function sendCeremonyHeader(title, url) {
+  const key = `${title}|${url}`;
+
+  // Prevent duplicate ceremony headers
+  if (ceremonySent.has(key)) {
+    return;
+  }
+
+  ceremonySent.add(key);
+  const content = `${boldCyan(title)}\n${gray('Documentation:')} ${cyan(url)}`;
+  messageManager.send(MessageType.CEREMONY_HEADER, content);
+}
+
+/**
+ * Send a progress message (shows in executing state)
+ *
+ * @param {string} message - Progress message
+ *
+ * @example
+ * sendProgress('Analyzing database requirements...');
+ */
+export function sendProgress(message) {
+  messageManager.send(MessageType.PROGRESS, message);
+}
+
+/**
+ * Send a substep message (detailed progress)
+ *
+ * @param {string} message - Substep message
+ *
+ * @example
+ * sendSubstep('Calling Claude API...');
+ */
+export function sendSubstep(message) {
+  messageManager.send(MessageType.SUBSTEP, message);
+}
+
+/**
+ * Send user output (main content)
+ *
+ * @param {string} content - Content to display
+ *
+ * @example
+ * sendOutput('Mission statement: Build a task manager\n');
+ */
+export function sendOutput(content) {
+  messageManager.send(MessageType.USER_OUTPUT, content);
+}
+
+/**
+ * Send an error message
+ *
+ * @param {string} message - Error message
+ *
+ * @example
+ * sendError('Failed to load configuration file');
+ */
+export function sendError(message) {
+  messageManager.send(MessageType.ERROR, message);
+}
+
+/**
+ * Send a warning message
+ *
+ * @param {string} message - Warning message
+ *
+ * @example
+ * sendWarning('API rate limit approaching');
+ */
+export function sendWarning(message) {
+  messageManager.send(MessageType.WARNING, message);
+}
+
+/**
+ * Send a success message
+ *
+ * @param {string} message - Success message
+ *
+ * @example
+ * sendSuccess('Documentation generated successfully');
+ */
+export function sendSuccess(message) {
+  messageManager.send(MessageType.SUCCESS, message);
+}
+
+/**
+ * Send an info message
+ *
+ * @param {string} message - Info message
+ *
+ * @example
+ * sendInfo('Using Claude provider for LLM operations');
+ */
+export function sendInfo(message) {
+  messageManager.send(MessageType.INFO, message);
+}
+
+/**
+ * Send a debug message (only to console.log)
+ *
+ * @param {string} message - Debug message
+ * @param {Object} data - Optional data to log
+ *
+ * @example
+ * sendDebug('Processing questionnaire', { currentIndex: 2, total: 6 });
+ */
+export function sendDebug(message, data = null) {
+  messageManager.send(MessageType.DEBUG, message, { data });
+}
+
+/**
+ * Clear progress indicators
+ *
+ * @example
+ * clearProgress();
+ */
+export function clearProgress() {
+  messageManager.clearProgress();
+}
+
+/**
+ * Get current execution context
+ *
+ * @returns {ExecutionContext|null} Current context or null
+ */
+export function getCurrentContext() {
+  return messageManager.getCurrentContext();
+}
+
+/**
+ * Check if current context is active
+ *
+ * @returns {boolean} True if active context exists
+ */
+export function isContextActive() {
+  const context = messageManager.getCurrentContext();
+  return context ? context.isActive() : false;
+}
+
+/**
+ * Register callbacks from React state
+ * Called once during REPL initialization
+ *
+ * @param {Object} callbacks - Callback functions
+ * @param {Function} callbacks.setExecutingMessage - setExecutingMessage React state setter
+ * @param {Function} callbacks.setExecutingSubstep - setExecutingSubstep React state setter
+ *
+ * @example
+ * // In repl-ink.js
+ * useEffect(() => {
+ *   registerCallbacks({
+ *     setExecutingMessage,
+ *     setExecutingSubstep
+ *   });
+ * }, []);
+ */
+export function registerCallbacks(callbacks) {
+  if (callbacks.setExecutingMessage) {
+    messageManager.setExecutingMessageCallback(callbacks.setExecutingMessage);
+  }
+  if (callbacks.setExecutingSubstep) {
+    messageManager.setExecutingSubstepCallback(callbacks.setExecutingSubstep);
+  }
+}
+
+/**
+ * Helper: Send formatted section header (cyan bold)
+ *
+ * @param {string} title - Section title
+ *
+ * @example
+ * sendSectionHeader('Database Options Comparison');
+ */
+export function sendSectionHeader(title) {
+  sendOutput(`\n${title}\n\n`);
+}
+
+/**
+ * Helper: Send formatted list item
+ *
+ * @param {string} item - List item text
+ * @param {number} indent - Indentation level (default: 0)
+ *
+ * @example
+ * sendListItem('PostgreSQL - ACID compliant');
+ * sendListItem('Supports complex queries', 1);
+ */
+export function sendListItem(item, indent = 0) {
+  const spacing = '  '.repeat(indent);
+  sendOutput(`${spacing}- ${item}\n`);
+}
+
+/**
+ * Helper: Send indented content
+ *
+ * @param {string} content - Content to indent
+ * @param {number} level - Indentation level (0-3, each level = 2 spaces)
+ *
+ * @example
+ * sendIndented('Details about the option', 1);
+ * sendIndented('Nested information', 2);
+ */
+export function sendIndented(content, level = 0) {
+  const spacing = '  '.repeat(level);
+  sendOutput(`${spacing}${content}`);
+}
+
+/**
+ * Helper: Send newline
+ */
+export function sendNewline() {
+  sendOutput('\n');
+}
+
+/**
+ * Helper: Send multiple newlines
+ *
+ * @param {number} count - Number of newlines (default: 2)
+ */
+export function sendNewlines(count = 2) {
+  sendOutput('\n'.repeat(count));
+}