@covibes/zeroshot 1.0.2 → 1.1.4

package/CHANGELOG.md

@@ -1,3 +1,57 @@
+## [1.1.4](https://github.com/covibes/zeroshot/compare/v1.1.3...v1.1.4) (2025-12-28)
+
+
+### Bug Fixes
+
+* **cli:** read version from package.json instead of hardcoded value ([a6e0e57](https://github.com/covibes/zeroshot/commit/a6e0e570feeaffa64dbc46d494eeef000f32b708))
+* **cli:** resolve streaming mode crash and refactor message formatters ([efb9264](https://github.com/covibes/zeroshot/commit/efb9264ce0d3ede0eb7d502d4625694c2c525230))
+
+## [1.1.3](https://github.com/covibes/zeroshot/compare/v1.1.2...v1.1.3) (2025-12-28)
+
+
+### Bug Fixes
+
+* **publish:** remove tests from prepublishOnly to prevent double execution ([3e11e71](https://github.com/covibes/zeroshot/commit/3e11e71cb722f835634d21f80fee79ea3c29b031))
+
+## [1.1.2](https://github.com/covibes/zeroshot/compare/v1.1.1...v1.1.2) (2025-12-28)
+
+
+### Bug Fixes
+
+* **ci:** resolve ESLint violations and status-footer test failures ([0d794f9](https://github.com/covibes/zeroshot/commit/0d794f98aa10d2492d8ab0af516bb1e5abee0566))
+* **isolation:** handle missing/directory .gitconfig in CI environments ([3d754e4](https://github.com/covibes/zeroshot/commit/3d754e4a02d40e2fd902d97d17a6532ba247f780))
+* **workflow:** extract tarball filename correctly from npm pack output ([3cf48a3](https://github.com/covibes/zeroshot/commit/3cf48a3ddf4f1938916c7ed5a2be1796003a988f))
+
+## [1.1.1](https://github.com/covibes/zeroshot/compare/v1.1.0...v1.1.1) (2025-12-28)
+
+
+### Bug Fixes
+
+* **lint:** resolve require-await and unused-imports errors ([852c8a0](https://github.com/covibes/zeroshot/commit/852c8a0e9076eb5403105c6f319e66e53c27fd6d))
+
+# [1.1.0](https://github.com/covibes/zeroshot/compare/v1.0.2...v1.1.0) (2025-12-28)
+
+
+### Bug Fixes
+
+* **docker:** use repo root as build context for Dockerfile ([c1d6719](https://github.com/covibes/zeroshot/commit/c1d6719eb43787ba62e5f69663eb4e5bd1aeb492))
+* **lint:** remove unused import and fix undefined variable in test ([41c9965](https://github.com/covibes/zeroshot/commit/41c9965eb84d2b8c22eaaf8e1d65a5f41c7b1e44))
+
+
+### Features
+
+* **isolation:** use zeroshot task infrastructure inside containers ([922f30d](https://github.com/covibes/zeroshot/commit/922f30d5ddd8c4d87cac375fd97025f402e7c43e))
+* **monitoring:** add live status footer with CPU/memory metrics ([2df3de0](https://github.com/covibes/zeroshot/commit/2df3de0a1fe9573961b596da9e78a159f3c33086))
+* **validators:** add zero-tolerance rejection rules for incomplete code ([308aef8](https://github.com/covibes/zeroshot/commit/308aef8b5ee2e3ff05e336ee810b842492183b2e))
+* **validators:** strengthen with senior engineering principles ([d83f666](https://github.com/covibes/zeroshot/commit/d83f6668a145e36bd7d807d9821e8631a3a1cc18))
+
+## [1.0.2](https://github.com/covibes/zeroshot/compare/v1.0.1...v1.0.2) (2025-12-27)
+
+
+### Bug Fixes
+
+* include task-lib in npm package ([37602fb](https://github.com/covibes/zeroshot/commit/37602fb3f1f6cd735d8db232be5829dc342b815d))
+
 ## [1.0.1](https://github.com/covibes/zeroshot/compare/v1.0.0...v1.0.1) (2025-12-27)
 
 

package/README.md

@@ -4,6 +4,8 @@
 [![Node 18+](https://img.shields.io/badge/node-18%2B-brightgreen.svg)](https://nodejs.org/)
 [![Platform: Linux | macOS](https://img.shields.io/badge/platform-Linux%20%7C%20macOS-blue.svg)]()
 
+> **2024** was the year of LLMs. **2025** was the year of agents. **2026** is the year of agent clusters.
+
 **Multi-agent coding CLI built on Claude Code.**
 
 You know the problem. Your AI agent:

package/cli/index.js

@@ -22,6 +22,23 @@ const chalk = require('chalk');
 const Orchestrator = require('../src/orchestrator');
 const { setupCompletion } = require('../lib/completion');
 const { parseChunk } = require('../lib/stream-json-parser');
+const { formatWatchMode } = require('./message-formatters-watch');
+const {
+  formatAgentLifecycle,
+  formatAgentError: formatAgentErrorNormal,
+  formatIssueOpened: formatIssueOpenedNormal,
+  formatImplementationReady: formatImplementationReadyNormal,
+  formatValidationResult: formatValidationResultNormal,
+  formatPrCreated,
+  formatClusterComplete,
+  formatClusterFailed,
+  formatGenericMessage,
+} = require('./message-formatters-normal');
+const {
+  getColorForSender,
+  buildMessagePrefix,
+  buildClusterPrefix,
+} = require('./message-formatter-utils');
 const {
   loadSettings,
   saveSettings,
@@ -29,6 +46,8 @@ const {
   coerceValue,
   DEFAULT_SETTINGS,
 } = require('../lib/settings');
+const { requirePreflight } = require('../src/preflight');
+const { StatusFooter } = require('../src/status-footer');
 
 const program = new Command();
 
@@ -317,16 +336,12 @@ if (shouldShowBanner) {
   showBanner();
 }
 
-// Color palette for agents (avoid green/red - reserved for APPROVED/REJECTED)
-const COLORS = [chalk.cyan, chalk.yellow, chalk.magenta, chalk.blue, chalk.white, chalk.gray];
-
-// Map agent IDs to colors
-const agentColors = new Map();
+// NOTE: Agent color handling moved to message-formatter-utils.js
 
 program
   .name('zeroshot')
   .description('Multi-agent orchestration and task management for Claude')
-  .version('1.0.0')
+  .version(require('../package.json').version)
   .addHelpText(
     'after',
     `
@@ -423,6 +438,16 @@ Input formats:
         input.text = inputArg;
       }
 
+      // === PREFLIGHT CHECKS ===
+      // Validate all dependencies BEFORE starting anything
+      // This gives users clear, actionable error messages upfront
+      const preflightOptions = {
+        requireGh: !!input.issue, // gh CLI required when fetching GitHub issues
+        requireDocker: options.isolation || options.full, // Docker required for isolation mode
+        quiet: process.env.CREW_DAEMON === '1', // Suppress success in daemon mode
+      };
+      requirePreflight(preflightOptions);
+
       // === CLUSTER MODE ===
       // Validate --pr requires --isolation
       if (options.pr && !options.isolation) {
@@ -580,6 +605,60 @@ Input formats:
         // Track messages we've already processed (to avoid duplicates between history and subscription)
         const processedMessageIds = new Set();
 
+        // === STATUS FOOTER: Live agent monitoring ===
+        // Shows CPU, memory, network metrics for all agents at bottom of terminal
+        const statusFooter = new StatusFooter({
+          refreshInterval: 1000,
+          enabled: process.stdout.isTTY,
+        });
+        statusFooter.setCluster(clusterId);
+        statusFooter.setClusterState('running');
+
+        // Subscribe to AGENT_LIFECYCLE to track agent states and PIDs
+        const lifecycleUnsubscribe = cluster.messageBus.subscribeTopic('AGENT_LIFECYCLE', (msg) => {
+          const data = msg.content?.data || {};
+          const event = data.event;
+          const agentId = data.agent || msg.sender;
+
+          // Update agent state based on lifecycle event
+          if (event === 'STARTED') {
+            statusFooter.updateAgent({
+              id: agentId,
+              state: 'idle',
+              pid: null,
+              iteration: data.iteration || 0,
+            });
+          } else if (event === 'TASK_STARTED') {
+            statusFooter.updateAgent({
+              id: agentId,
+              state: 'executing',
+              pid: statusFooter.agents.get(agentId)?.pid || null,
+              iteration: data.iteration || 0,
+            });
+          } else if (event === 'PROCESS_SPAWNED') {
+            // Got the PID - update the agent with it
+            const current = statusFooter.agents.get(agentId) || { state: 'executing', iteration: 0 };
+            statusFooter.updateAgent({
+              id: agentId,
+              state: current.state,
+              pid: data.pid,
+              iteration: current.iteration,
+            });
+          } else if (event === 'TASK_COMPLETED' || event === 'TASK_FAILED') {
+            statusFooter.updateAgent({
+              id: agentId,
+              state: 'idle',
+              pid: null,
+              iteration: data.iteration || 0,
+            });
+          } else if (event === 'STOPPED') {
+            statusFooter.removeAgent(agentId);
+          }
+        });
+
+        // Start the status footer
+        statusFooter.start();
+
         // Message handler - processes messages, deduplicates by ID
         const handleMessage = (msg) => {
           if (msg.cluster_id !== clusterId) return;
@@ -618,6 +697,9 @@ Input formats:
               if (status.state !== 'running') {
                 clearInterval(checkInterval);
                 clearInterval(flushInterval);
+                // Stop status footer
+                statusFooter.stop();
+                lifecycleUnsubscribe();
                 // Final flush
                 for (const sender of sendersWithOutput) {
                   const prefix = getColorForSender(sender)(`${sender.padEnd(15)} |`);
@@ -630,6 +712,8 @@ Input formats:
               // Cluster may have been removed
               clearInterval(checkInterval);
               clearInterval(flushInterval);
+              statusFooter.stop();
+              lifecycleUnsubscribe();
               unsubscribe();
               resolve();
             }
@@ -639,6 +723,10 @@ Input formats:
           // CRITICAL: In foreground mode, the cluster runs IN this process.
           // If we exit without stopping, the cluster becomes a zombie (state=running but no process).
           process.on('SIGINT', async () => {
+            // Stop status footer first to restore terminal
+            statusFooter.stop();
+            lifecycleUnsubscribe();
+
             console.log(chalk.dim('\n\n--- Interrupted ---'));
             clearInterval(checkInterval);
             clearInterval(flushInterval);
@@ -752,6 +840,14 @@ taskCmd
   .option('--silent-json-output', 'Log ONLY final structured output')
   .action(async (prompt, options) => {
     try {
+      // === PREFLIGHT CHECKS ===
+      // Claude CLI must be installed and authenticated for task execution
+      requirePreflight({
+        requireGh: false, // gh not needed for plain tasks
+        requireDocker: false, // Docker not needed for plain tasks
+        quiet: false,
+      });
+
       // Dynamically import task command (ESM module)
       const { runTask } = await import('../task-lib/commands/run.js');
       await runTask(prompt, options);
@@ -1886,6 +1982,16 @@ program
       // Check if cluster exists
       const cluster = orchestrator.getCluster(id);
 
+      // === PREFLIGHT CHECKS ===
+      // Claude CLI must be installed and authenticated
+      // Check if cluster uses isolation (needs Docker)
+      const requiresDocker = cluster?.isolation?.enabled || false;
+      requirePreflight({
+        requireGh: false, // Resume doesn't fetch new issues
+        requireDocker: requiresDocker,
+        quiet: false,
+      });
+
       if (cluster) {
         // Resume cluster
         console.log(chalk.cyan(`Resuming cluster ${id}...`));
@@ -2928,18 +3034,6 @@ function formatToolResult(content, isError, toolName, toolInput) {
 
 // Helper function to get deterministic color for an agent/sender based on name hash
 // Uses djb2 hash algorithm for good distribution across color palette
-function getColorForSender(sender) {
-  if (!agentColors.has(sender)) {
-    let hash = 5381;
-    for (let i = 0; i < sender.length; i++) {
-      hash = (hash << 5) + hash + sender.charCodeAt(i);
-    }
-    const colorIndex = Math.abs(hash) % COLORS.length;
-    agentColors.set(sender, COLORS[colorIndex]);
-  }
-  return agentColors.get(sender);
-}
-
 // Track recently seen content to avoid duplicates
 const recentContentHashes = new Set();
 const MAX_RECENT_HASHES = 100;
@@ -3546,166 +3640,62 @@ const FILTERED_PATTERNS = [
 
 // Helper function to print a message (docker-compose style with colors)
 function printMessage(msg, showClusterId = false, watchMode = false, isActive = true) {
+  // Build prefix using utility function
+  const prefix = buildMessagePrefix(msg, showClusterId, isActive);
+
   const timestamp = new Date(msg.timestamp).toLocaleTimeString('en-US', {
     hour12: false,
   });
-  // Use dim colors for inactive clusters
-  const color = isActive ? getColorForSender(msg.sender) : chalk.dim;
 
-  // Build prefix with optional cluster ID and model (sender_model is set by agent-wrapper._publish)
-  let senderLabel = msg.sender;
-  if (showClusterId && msg.cluster_id) {
-    senderLabel = `${msg.cluster_id}/${msg.sender}`;
-  }
-  const modelSuffix = msg.sender_model ? chalk.dim(` [${msg.sender_model}]`) : '';
-  const prefix = color(`${senderLabel.padEnd(showClusterId ? 25 : 15)} |`) + modelSuffix;
-
-  // Watch mode: ONLY show high-level business events in human-readable format
+  // Watch mode: delegate to watch mode formatter
   if (watchMode) {
-    // Skip low-level topics (too noisy for watch mode)
-    if (msg.topic === 'AGENT_OUTPUT' || msg.topic === 'AGENT_LIFECYCLE') {
-      return;
-    }
-
-    // Clear status line, print message, will be redrawn by status interval
-    process.stdout.write('\r' + ' '.repeat(120) + '\r');
-
-    // Simplified prefix for watch mode: just cluster ID (white = alive, grey = dead)
-    const clusterPrefix = isActive
-      ? chalk.white(`${msg.cluster_id.padEnd(20)} |`)
-      : chalk.dim(`${msg.cluster_id.padEnd(20)} |`);
-
-    // AGENT_ERROR: Show errors prominently
-    if (msg.topic === 'AGENT_ERROR') {
-      const errorMsg = `${msg.sender} ${chalk.bold.red('ERROR')}`;
-      console.log(`${clusterPrefix} ${errorMsg}`);
-      if (msg.content?.text) {
-        console.log(`${clusterPrefix}   ${chalk.red(msg.content.text)}`);
-      }
-      return;
-    }
-
-    // Human-readable event descriptions (with consistent agent colors)
-    const agentColor = getColorForSender(msg.sender);
-    const agentName = agentColor(msg.sender);
-    let eventText = '';
-
-    switch (msg.topic) {
-      case 'ISSUE_OPENED':
-        const issueNum = msg.content?.data?.issue_number || '';
-        const title = msg.content?.data?.title || '';
-        const prompt = msg.content?.data?.prompt || msg.content?.text || '';
-
-        // If it's manual input, show the prompt instead of "Manual Input"
-        const taskDesc = title === 'Manual Input' && prompt ? prompt : title;
-        const truncatedDesc =
-          taskDesc && taskDesc.length > 60 ? taskDesc.substring(0, 60) + '...' : taskDesc;
-
-        eventText = `Started ${issueNum ? `#${issueNum}` : 'task'}${truncatedDesc ? chalk.dim(` - ${truncatedDesc}`) : ''}`;
-        break;
-
-      case 'IMPLEMENTATION_READY':
-        eventText = `${agentName} completed implementation`;
-        break;
-
-      case 'VALIDATION_RESULT':
-        const data = msg.content?.data;
-        const approved = data?.approved === 'true' || data?.approved === true;
-        const status = approved ? chalk.green('APPROVED') : chalk.red('REJECTED');
-        eventText = `${agentName} ${status}`;
-        if (data?.summary && !approved) {
-          eventText += chalk.dim(` - ${data.summary}`);
-        }
-        console.log(`${clusterPrefix} ${eventText}`);
-
-        // Show rejection details (character counts only)
-        if (!approved) {
-          let errors = data.errors;
-          let issues = data.issues;
-
-          if (typeof errors === 'string') {
-            try {
-              errors = JSON.parse(errors);
-            } catch {
-              errors = [];
-            }
-          }
-          if (typeof issues === 'string') {
-            try {
-              issues = JSON.parse(issues);
-            } catch {
-              issues = [];
-            }
-          }
+    const clusterPrefix = buildClusterPrefix(msg, isActive);
+    formatWatchMode(msg, clusterPrefix);
+    return;
+  }
 
-          // Calculate total character counts
-          let errorsCharCount = 0;
-          let issuesCharCount = 0;
+  // Normal mode: delegate to appropriate formatter based on topic
+  if (msg.topic === 'AGENT_LIFECYCLE') {
+    formatAgentLifecycle(msg, prefix);
+    return;
+  }
 
-          if (Array.isArray(errors) && errors.length > 0) {
-            errorsCharCount = JSON.stringify(errors).length;
-            console.log(
-              `${clusterPrefix}   ${chalk.red('•')} ${errors.length} error${errors.length > 1 ? 's' : ''} (${errorsCharCount} chars)`
-            );
-          }
+  if (msg.topic === 'AGENT_ERROR') {
+    formatAgentErrorNormal(msg, prefix, timestamp);
+    return;
+  }
 
-          if (Array.isArray(issues) && issues.length > 0) {
-            issuesCharCount = JSON.stringify(issues).length;
-            console.log(
-              `${clusterPrefix}   ${chalk.yellow('•')} ${issues.length} issue${issues.length > 1 ? 's' : ''} (${issuesCharCount} chars)`
-            );
-          }
-        }
-        return;
+  if (msg.topic === 'ISSUE_OPENED') {
+    formatIssueOpenedNormal(msg, prefix, timestamp, shownNewTaskForCluster);
+    return;
+  }
 
-      case 'PR_CREATED':
-        const prNum = msg.content?.data?.pr_number || '';
-        eventText = `${agentName} created PR${prNum ? ` #${prNum}` : ''}`;
-        break;
+  if (msg.topic === 'IMPLEMENTATION_READY') {
+    formatImplementationReadyNormal(msg, prefix, timestamp);
+    return;
+  }
 
-      case 'PR_MERGED':
-        eventText = `${agentName} merged PR`;
-        break;
+  if (msg.topic === 'VALIDATION_RESULT') {
+    formatValidationResultNormal(msg, prefix, timestamp);
+    return;
+  }
 
-      default:
-        // Fallback for unknown topics
-        eventText = `${agentName} ${msg.topic.toLowerCase().replace(/_/g, ' ')}`;
-    }
+  if (msg.topic === 'PR_CREATED') {
+    formatPrCreated(msg, prefix, timestamp);
+    return;
+  }
 
-    console.log(`${clusterPrefix} ${eventText}`);
+  if (msg.topic === 'CLUSTER_COMPLETE') {
+    formatClusterComplete(msg, prefix, timestamp);
     return;
   }
 
-  // AGENT_LIFECYCLE: Show agent start/trigger/task events
-  if (msg.topic === 'AGENT_LIFECYCLE') {
-    const data = msg.content?.data;
-    const event = data?.event;
-
-    let icon, eventText;
-    switch (event) {
-      case 'STARTED':
-        icon = chalk.green('▶');
-        const triggers = data.triggers?.join(', ') || 'none';
-        eventText = `started (listening for: ${chalk.dim(triggers)})`;
-        break;
-      case 'TASK_STARTED':
-        icon = chalk.yellow('⚡');
-        eventText = `${chalk.cyan(data.triggeredBy)} → task #${data.iteration} (${chalk.dim(data.model)})`;
-        break;
-      case 'TASK_COMPLETED':
-        icon = chalk.green('✓');
-        eventText = `task #${data.iteration} completed`;
-        break;
-      default:
-        icon = chalk.dim('•');
-        eventText = event || 'unknown event';
-    }
-
-    console.log(`${prefix} ${icon} ${eventText}`);
+  if (msg.topic === 'CLUSTER_FAILED') {
+    formatClusterFailed(msg, prefix, timestamp);
     return;
   }
 
-  // AGENT_OUTPUT: parse streaming JSON and display all content
+  // AGENT_OUTPUT: handle separately (complex streaming logic - kept in main file due to dependencies)
   if (msg.topic === 'AGENT_OUTPUT') {
     // Support both old 'chunk' and new 'line' formats
     const content = msg.content?.data?.line || msg.content?.data?.chunk || msg.content?.text;
@@ -3917,55 +3907,8 @@ function printMessage(msg, showClusterId = false, watchMode = false, isActive =
     return;
   }
 
-  // PR_CREATED: show PR created banner
-  if (msg.topic === 'PR_CREATED') {
-    console.log('');
-    console.log(chalk.bold.green(`${'─'.repeat(60)}`));
-    console.log(`${prefix} ${chalk.gray(timestamp)} ${chalk.bold.green('🔗 PR CREATED')}`);
-    if (msg.content?.data?.pr_url) {
-      console.log(`${prefix} ${chalk.cyan(msg.content.data.pr_url)}`);
-    }
-    if (msg.content?.data?.merged) {
-      console.log(`${prefix} ${chalk.bold.cyan('✓ MERGED')}`);
-    }
-    console.log(chalk.bold.green(`${'─'.repeat(60)}`));
-    return;
-  }
-
-  // CLUSTER_COMPLETE: show completion banner
-  if (msg.topic === 'CLUSTER_COMPLETE') {
-    console.log('');
-    console.log(chalk.bold.green(`${'═'.repeat(60)}`));
-    console.log(`${prefix} ${chalk.gray(timestamp)} ${chalk.bold.green('✅ CLUSTER COMPLETED')}`);
-    if (msg.content?.text) {
-      console.log(`${prefix} ${chalk.white(msg.content.text)}`);
-    }
-    if (msg.content?.data?.reason) {
-      console.log(`${prefix} ${chalk.dim('Reason:')} ${msg.content.data.reason}`);
-    }
-    console.log(chalk.bold.green(`${'═'.repeat(60)}`));
-    console.log('');
-    return;
-  }
-
-  // Other topics: generic display
-  const topicColor = msg.topic.startsWith('TASK_')
-    ? chalk.bold.green
-    : msg.topic.startsWith('ERROR')
-      ? chalk.bold.red
-      : chalk.bold;
-
-  console.log(`${prefix} ${chalk.gray(timestamp)} ${topicColor(msg.topic)}`);
-
-  // Show text content (skip template variables)
-  if (msg.content?.text && !msg.content.text.includes('{{')) {
-    const lines = msg.content.text.split('\n');
-    for (const line of lines) {
-      if (line.trim()) {
-        console.log(`${prefix} ${line}`);
-      }
-    }
-  }
+  // Fallback: generic message display for unknown topics
+  formatGenericMessage(msg, prefix, timestamp);
 }
 
 // Default command handling: if first arg doesn't match a known command, treat it as 'run'

package/cli/message-formatter-utils.js

@@ -0,0 +1,75 @@
+/**
+ * Message formatting utilities for CLI output
+ * Extracted from index.js to reduce complexity
+ */
+
+const chalk = require('chalk');
+
+/**
+ * Get color for sender based on consistent hashing
+ * @param {string} sender - Sender name
+ * @returns {Function} Chalk color function
+ */
+function getColorForSender(sender) {
+  const colors = [chalk.cyan, chalk.magenta, chalk.yellow, chalk.green, chalk.blue];
+  let hash = 0;
+  for (let i = 0; i < sender.length; i++) {
+    hash = (hash << 5) - hash + sender.charCodeAt(i);
+    hash = hash & hash;
+  }
+  return colors[Math.abs(hash) % colors.length];
+}
+
+/**
+ * Build message prefix with timestamp, sender, and optional cluster ID
+ * @param {Object} msg - Message object
+ * @param {boolean} showClusterId - Whether to show cluster ID
+ * @param {boolean} isActive - Whether cluster is active
+ * @returns {string} Formatted prefix
+ */
+function buildMessagePrefix(msg, showClusterId, isActive) {
+  const color = isActive ? getColorForSender(msg.sender) : chalk.dim;
+
+  let senderLabel = msg.sender;
+  if (showClusterId && msg.cluster_id) {
+    senderLabel = `${msg.cluster_id}/${msg.sender}`;
+  }
+
+  const modelSuffix = msg.sender_model ? chalk.dim(` [${msg.sender_model}]`) : '';
+  return color(`${senderLabel.padEnd(showClusterId ? 25 : 15)} |`) + modelSuffix;
+}
+
+/**
+ * Build cluster prefix for watch mode
+ * @param {string} clusterId - Cluster ID
+ * @param {boolean} isActive - Whether cluster is active
+ * @returns {string} Formatted prefix
+ */
+function buildClusterPrefix(clusterId, isActive) {
+  return isActive
+    ? chalk.white(`${clusterId.padEnd(20)} |`)
+    : chalk.dim(`${clusterId.padEnd(20)} |`);
+}
+
+/**
+ * Parse and normalize data fields (handles string JSON)
+ * @param {string|Array} data - Data to parse
+ * @returns {Array} Parsed array
+ */
+function parseDataField(data) {
+  if (typeof data === 'string') {
+    try {
+      return JSON.parse(data);
+    } catch {
+      return [];
+    }
+  }
+  return Array.isArray(data) ? data : [];
+}
+
+module.exports = {
+  getColorForSender,
+  buildMessagePrefix,
+  buildClusterPrefix,
+  parseDataField,
+};