feat(cli): add websocket command and improve runtime diagnostics

Author: GaspardKirira

CMakeLists.txt

@@ -152,6 +152,7 @@ else()
   set(_VIX_SYNC_DIR     "${_VIX_MODULES_DIR}/sync")
   set(_VIX_CACHE_DIR    "${_VIX_MODULES_DIR}/cache")
   set(_VIX_AGENT_DIR    "${_VIX_MODULES_DIR}/agent")
+  set(_VIX_WEBSOCKET_DIR "${_VIX_MODULES_DIR}/websocket")
 
   set(_LOCAL_LAYOUT_OK FALSE)
   if (EXISTS "${_VIX_CORE_DIR}/CMakeLists.txt" AND EXISTS "${_VIX_UTILS_DIR}/CMakeLists.txt")
@@ -205,6 +206,11 @@ else()
       add_subdirectory("${_VIX_AGENT_DIR}" "${CMAKE_BINARY_DIR}/_vix_ai_agent")
     endif()
 
+    if (EXISTS "${_VIX_WEBSOCKET_DIR}/CMakeLists.txt" AND NOT TARGET vix::websocket)
+      set(VIX_WEBSOCKET_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
+      add_subdirectory("${_VIX_WEBSOCKET_DIR}" "${CMAKE_BINARY_DIR}/_vix_websocket")
+    endif()
+
     if (EXISTS "${_VIX_P2P_DIR}/CMakeLists.txt" AND NOT TARGET vix::p2p)
       add_subdirectory("${_VIX_P2P_DIR}" "${CMAKE_BINARY_DIR}/_vix_p2p")
     endif()
@@ -253,6 +259,10 @@ else()
       list(APPEND _VIX_LOCAL_LINK_TARGETS vix::ai_agent)
     endif()
 
+    if (TARGET vix::websocket)
+      list(APPEND _VIX_LOCAL_LINK_TARGETS vix::websocket)
+    endif()
+
     if (TARGET vix::p2p)
       list(APPEND _VIX_LOCAL_LINK_TARGETS vix::p2p)
     endif()
@@ -269,6 +279,7 @@ else()
     vix_append_if_exists(_VIX_LOCAL_INCLUDE_DIRS "${_VIX_SYNC_DIR}/include")
     vix_append_if_exists(_VIX_LOCAL_INCLUDE_DIRS "${_VIX_CACHE_DIR}/include")
     vix_append_if_exists(_VIX_LOCAL_INCLUDE_DIRS "${_VIX_AGENT_DIR}/include")
+    vix_append_if_exists(_VIX_LOCAL_INCLUDE_DIRS "${_VIX_WEBSOCKET_DIR}/include")
     vix_append_if_exists(_VIX_LOCAL_INCLUDE_DIRS "${_VIX_P2P_DIR}/include")
 
     if (_VIX_LOCAL_LINK_TARGETS)
@@ -330,6 +341,17 @@ else()
   message(STATUS "[cli] Game command disabled: vix::game target not found")
 endif()
 
+# ----------------------------------------------------
+# Optional websocket command support
+# ----------------------------------------------------
+if (TARGET vix::websocket)
+  message(STATUS "[cli] WebSocket command enabled")
+  target_link_libraries(vix_cli PRIVATE vix::websocket)
+  target_compile_definitions(vix_cli PRIVATE VIX_CLI_HAS_WEBSOCKET=1)
+else()
+  message(STATUS "[cli] WebSocket command disabled: vix::websocket target not found")
+endif()
+
 if (TARGET vix_warnings)
   target_link_libraries(vix_cli PRIVATE vix_warnings)
 endif()

include/vix/cli/commands/WsCommand.hpp

@@ -0,0 +1,54 @@
+/**
+ *
+ *  @file WsCommand.hpp
+ *  @author Gaspard Kirira
+ *
+ *  Copyright 2026, Gaspard Kirira.  All rights reserved.
+ *  https://github.com/vixcpp/vix
+ *  Use of this source code is governed by a MIT license
+ *  that can be found in the License file.
+ *
+ *  Vix.cpp
+ */
+#ifndef VIX_WS_COMMAND_HPP
+#define VIX_WS_COMMAND_HPP
+
+#include <string>
+#include <vector>
+
+namespace vix::commands
+{
+  /**
+   * @brief Command entry point for WebSocket production diagnostics.
+   */
+  struct WsCommand
+  {
+    /**
+     * @brief Run the ws command.
+     *
+     * Supported forms:
+     *
+     * `vix ws check`
+     * `vix ws check ws://127.0.0.1:9090/ws`
+     *
+     * Options:
+     *
+     * `--timeout <ms>`
+     * `--no-ping`
+     * `--verbose`
+     *
+     * @param args Command arguments after `ws`.
+     * @return Process exit code.
+     */
+    static int run(const std::vector<std::string> &args);
+
+    /**
+     * @brief Print ws command help.
+     *
+     * @return Process exit code.
+     */
+    static int help();
+  };
+}
+
+#endif

include/vix/cli/commands/ws/WsChecker.hpp

@@ -0,0 +1,35 @@
+/**
+ *
+ *  @file WsChecker.hpp
+ *  @author Gaspard Kirira
+ *
+ *  Copyright 2026, Gaspard Kirira.  All rights reserved.
+ *  https://github.com/vixcpp/vix
+ *  Use of this source code is governed by a MIT license
+ *  that can be found in the License file.
+ *
+ *  Vix.cpp
+ */
+#ifndef VIX_WS_CHECKER_HPP
+#define VIX_WS_CHECKER_HPP
+
+#include <vix/cli/commands/ws/WsTypes.hpp>
+
+namespace vix::commands::ws::checker
+{
+  /**
+   * @brief Check a WebSocket endpoint.
+   *
+   * The checker validates the URL, extracts host/port/path, attempts a native
+   * WebSocket connection and reports handshake/connectivity diagnostics.
+   *
+   * @param cfg Effective WebSocket configuration.
+   * @param options Runtime WebSocket options.
+   * @return Process exit code.
+   */
+  int check(
+      const WsConfig &cfg,
+      const WsOptions &options);
+}
+
+#endif

include/vix/cli/commands/ws/WsConfig.hpp

@@ -0,0 +1,58 @@
+/**
+ *
+ *  @file WsConfig.hpp
+ *  @author Gaspard Kirira
+ *
+ *  Copyright 2026, Gaspard Kirira.  All rights reserved.
+ *  https://github.com/vixcpp/vix
+ *  Use of this source code is governed by a MIT license
+ *  that can be found in the License file.
+ *
+ *  Vix.cpp
+ */
+#ifndef VIX_WS_CONFIG_HPP
+#define VIX_WS_CONFIG_HPP
+
+#include <vix/cli/commands/ws/WsTypes.hpp>
+
+#include <optional>
+#include <string>
+
+namespace vix::commands::ws
+{
+  /**
+   * @brief Read the current Vix project name.
+   *
+   * The project name is resolved from `vix.json` when available.
+   * If no project name is found, the implementation may fall back to
+   * the current directory name.
+   *
+   * @return The detected project name, or std::nullopt if no name can be resolved.
+   */
+  std::optional<std::string> read_project_name();
+
+  /**
+   * @brief Load production WebSocket configuration from vix.json.
+   *
+   * The configuration is read from:
+   * - `production.websocket`
+   * - `production.proxy.websocket`
+   * - core `websocket.*` values when available
+   *
+   * @return Loaded WebSocket configuration.
+   */
+  WsConfig load_ws_config();
+
+  /**
+   * @brief Apply command-line ws options to the loaded config.
+   *
+   * @param cfg Loaded WebSocket configuration.
+   * @param options Runtime ws options.
+   * @return Effective WebSocket configuration.
+   */
+  WsConfig apply_ws_options(
+      WsConfig cfg,
+      const WsOptions &options);
+}
+
+#endif

include/vix/cli/commands/ws/WsOutput.hpp

@@ -0,0 +1,96 @@
+/**
+ *
+ *  @file WsOutput.hpp
+ *  @author Gaspard Kirira
+ *
+ *  Copyright 2026, Gaspard Kirira.  All rights reserved.
+ *  https://github.com/vixcpp/vix
+ *  Use of this source code is governed by a MIT license
+ *  that can be found in the License file.
+ *
+ *  Vix.cpp
+ */
+#ifndef VIX_WS_OUTPUT_HPP
+#define VIX_WS_OUTPUT_HPP
+
+#include <vix/cli/commands/ws/WsTypes.hpp>
+
+#include <iosfwd>
+#include <string>
+
+namespace vix::commands::ws::output
+{
+  /**
+   * @brief Print the WebSocket check summary.
+   *
+   * @param out Output stream.
+   * @param cfg Effective WebSocket configuration.
+   * @param options Runtime WebSocket options.
+   */
+  void print_summary(
+      std::ostream &out,
+      const WsConfig &cfg,
+      const WsOptions &options);
+
+  /**
+   * @brief Print the beginning of a WebSocket step.
+   *
+   * @param out Output stream.
+   * @param label Step label.
+   */
+  void step(
+      std::ostream &out,
+      const std::string &label);
+
+  /**
+   * @brief Print a key/value command line.
+   *
+   * @param out Output stream.
+   * @param command Command text.
+   */
+  void command(
+      std::ostream &out,
+      const std::string &command);
+
+  /**
+   * @brief Print a successful WebSocket operation message.
+   *
+   * @param out Output stream.
+   * @param message Message to print.
+   */
+  void ok(
+      std::ostream &out,
+      const std::string &message);
+
+  /**
+   * @brief Print a WebSocket warning message.
+   *
+   * @param out Output stream.
+   * @param message Message to print.
+   */
+  void warn(
+      std::ostream &out,
+      const std::string &message);
+
+  /**
+   * @brief Print a WebSocket error message.
+   *
+   * @param out Output stream.
+   * @param message Message to print.
+   */
+  void error(
+      std::ostream &out,
+      const std::string &message);
+
+  /**
+   * @brief Print a fix suggestion.
+   *
+   * @param out Output stream.
+   * @param message Fix suggestion.
+   */
+  void fix(
+      std::ostream &out,
+      const std::string &message);
+}
+
+#endif