zen hub command (#877)

- Feature: Added `zen hub` command for managing a hub server and its provisioned module instances:
  - `zen hub up` - Start a hub server (equivalent to `zen up` in hub mode)
  - `zen hub down` - Shut down a hub server
  - `zen hub provision <moduleid>` - Provision a storage server instance for a module
  - `zen hub deprovision <moduleid>` - Deprovision a storage server instance
  - `zen hub hibernate <moduleid>` - Hibernate a provisioned instance (shut down, data preserved)
  - `zen hub wake <moduleid>` - Wake a hibernated instance
  - `zen hub status [moduleid]` - Show state of all instances or a specific module
- Feature: Added new hub HTTP endpoints for instance lifecycle management:
  - `POST /hub/modules/{moduleid}/hibernate` - Hibernate the instance for the given module
  - `POST /hub/modules/{moduleid}/wake` - Wake a hibernated instance for the given module
- Improvement: `zen up` refactored to use shared `StartupZenServer`/`ShutdownZenServer` helpers (also used by `zen hub up`/`zen hub down`)
- Bugfix: Fixed shutdown event not being cleared after the server process exits in `ZenServerInstance::Shutdown()`, which could cause stale state on reuse

1 files changed, 26 insertions, 0 deletions

diff --git a/src/zenutil/include/zenutil/zenserverprocess.h b/src/zenutil/include/zenutil/zenserverprocess.h
index 308ae0ef2..daa07a1e1 100644
--- a/src/zenutil/include/zenutil/zenserverprocess.h
+++ b/src/zenutil/include/zenutil/zenserverprocess.h
@@ -12,6 +12,8 @@
 #include <filesystem>
 #include <functional>
 #include <optional>
+#include <stdexcept>
+#include <string>
 
 namespace zen {
 
@@ -330,4 +332,28 @@ CbObject	 MakeLockFilePayload(const LockFileInfo& Info);
 LockFileInfo ReadLockFilePayload(const CbObject& Payload);
 bool		 ValidateLockFileInfo(const LockFileInfo& Info, std::string& OutReason);
 
+struct StartupZenServerOptions
+{
+	std::filesystem::path		  ProgramBaseDir;  // empty = auto-resolve from running executable
+	uint16_t					  Port		  = 0;
+	bool						  OpenConsole = false;	// open a console window for the server process
+	bool						  ShowLog	  = false;	// emit captured server log to LogRef on successful start
+	std::string					  ExtraArgs;			// e.g. GlobalOptions.PassthroughCommandLine
+	ZenServerInstance::ServerMode Mode = ZenServerInstance::ServerMode::kStorageServer;
+};
+
+// Returns std::nullopt if a matching server is already running (no action taken); logs instance info via LogRef.
+// Returns 0 if the server was successfully started and is ready.
+// Returns a non-zero exit code if startup failed; the captured server log is emitted via LogRef before returning.
+std::optional<int> StartupZenServer(LoggerRef LogRef, const StartupZenServerOptions& Options);
+
+// Attempts graceful shutdown of a running server entry.
+// First tries ZenServerInstance::SignalShutdown; falls back to
+// ZenServerEntry::SignalShutdownRequest + polling.
+// Returns true on successful shutdown, false if it timed out.
+bool ShutdownZenServer(LoggerRef					   LogRef,
+					   ZenServerState&				   State,
+					   ZenServerState::ZenServerEntry* Entry,
+					   const std::filesystem::path&	   ProgramBaseDir);
+
 }  // namespace zen