swarmy 0.1.2 → 0.2.0

package/README.md

@@ -39,7 +39,35 @@ Provision ephemeral Docker containers across multiple nodes and interact with th
 - Docker
 - npm
 
-### Manager
+### Using npx (recommended)
+
+**Manager:**
+
+```bash
+npx --yes swarmy@latest manager start
+```
+
+This prints the token and connection instructions for workers.
+
+**Worker** (on each node):
+
+```bash
+npx --yes swarmy@latest worker start --url http://<manager-ip>:5174 --token <token>
+```
+
+**Other commands:**
+
+```bash
+npx swarmy manager status     # Show PID + token
+npx swarmy manager stop       # Stop manager
+npx swarmy manager restart    # Restart manager
+npx swarmy worker status      # Show worker PID
+npx swarmy worker stop        # Stop worker
+```
+
+### From source (development)
+
+**Manager:**
 
 ```bash
 cd manager
@@ -49,9 +77,7 @@ npm run dev
 
 The manager starts on port 5174. An auth token is auto-generated at `manager/data/token` on first run.
 
-### Worker
-
-On each node that will run containers:
+**Worker** (on each node):
 
 ```bash
 cd worker
@@ -90,7 +116,7 @@ Installs to `/opt/swarm`. Services auto-restart on failure.
 
 | Variable        | Component | Description                            |
 | --------------- | --------- | -------------------------------------- |
-| `PORT`          | Manager   | HTTP port (default: 3000)              |
+| `PORT`          | Manager   | HTTP port (default: 5174)              |
 | `SWARM_URL`     | Worker    | Manager URL to connect to              |
 | `SWARM_TOKEN`   | Worker    | Auth token for registration            |
 | `SWARM_NODE_ID` | Worker    | Node identifier (default: hostname)    |
@@ -110,6 +136,9 @@ All REST endpoints require `Authorization: Bearer <token>` header.
 | `POST`   | `/api/sessions`           | Spawn terminal session in container |
 | `DELETE` | `/api/sessions/:id`       | Kill session                        |
 | `POST`   | `/api/sessions/:id/input` | Send input to session               |
+| `PATCH`  | `/api/sessions/:id`       | Toggle interactive mode             |
+| `POST`   | `/api/containers/:id/thumbnail` | Upload VNC thumbnail (base64 JPEG) |
+| `GET`    | `/api/containers/:id/thumbnail` | Get VNC thumbnail (supports `?token=`) |
 | `GET`    | `/api/status`             | Server status                       |
 
 ## Tech Stack

package/bin/swarmy.js

@@ -139,31 +139,177 @@ const cliArgs = process.argv.slice(2);
 const role = cliArgs[0];
 const action = cliArgs[1];
 
-function usage() {
+const hasFlag = (flag) => cliArgs.includes(flag);
+
+function parseFlag(flag) {
+  const idx = cliArgs.indexOf(flag);
+  if (idx === -1 || idx + 1 >= cliArgs.length) return undefined;
+  return cliArgs[idx + 1];
+}
+
+function usageMain() {
   console.log(`
   swarmy - Distributed container management
 
   Usage:
-    swarmy manager start [--port PORT]
+    swarmy manager <command>    Manage the central server
+    swarmy worker <command>     Manage a worker node
+    swarmy --help               Show this help
+
+  Run 'swarmy manager --help' or 'swarmy worker --help' for command details.
+  `);
+  process.exit(0);
+}
+
+function usageManager() {
+  console.log(`
+  swarmy manager - Manage the central server
+
+  Commands:
+    start [--port PORT]   Start the manager (default port: 5174)
+    stop                  Stop the manager
+    restart [--port PORT] Restart the manager
+    status                Show manager status and token
+
+  Examples:
+    swarmy manager start
+    swarmy manager start --port 3000
+    swarmy manager status
+    swarmy manager stop
+  `);
+  process.exit(0);
+}
+
+function usageWorker() {
+  console.log(`
+  swarmy worker - Manage a worker node
+
+  Commands:
+    start --url URL --token TOKEN [--hostname NAME]
+                          Connect worker to a manager
+    stop                  Stop the worker
+    restart --url URL --token TOKEN [--hostname NAME]
+                          Restart the worker
+    status                Show worker status
+
+  Examples:
+    swarmy worker start --url http://192.168.1.10:5174 --token abc123
+    swarmy worker start --url http://manager:5174 --token abc123 --hostname gpu-node-01
+    swarmy worker status
+    swarmy worker stop
+  `);
+  process.exit(0);
+}
+
+// Only handle --help at top level (swarmy --help) or role level (swarmy manager --help)
+// Action-level help (swarmy manager start --help) is handled in the switch cases
+if (role === "--help" || role === "-h") usageMain();
+
+if (!role) usageMain();
+if (!action) {
+  if (role === "manager") usageManager();
+  else if (role === "worker") usageWorker();
+  else usageMain();
+}
+
+function usageManagerStart() {
+  console.log(`
+  swarmy manager start - Start the central server
+
+  Options:
+    --port PORT    HTTP port (default: 5174)
+
+  Examples:
+    swarmy manager start
+    swarmy manager start --port 3000
+  `);
+  process.exit(0);
+}
+
+function usageManagerStop() {
+  console.log(`
+  swarmy manager stop - Stop the central server
+
+  Usage:
     swarmy manager stop
-    swarmy manager restart [--port PORT]
+  `);
+  process.exit(0);
+}
+
+function usageManagerRestart() {
+  console.log(`
+  swarmy manager restart - Restart the central server
+
+  Options:
+    --port PORT    HTTP port (default: 5174)
+
+  Examples:
+    swarmy manager restart
+    swarmy manager restart --port 3000
+  `);
+  process.exit(0);
+}
+
+function usageManagerStatus() {
+  console.log(`
+  swarmy manager status - Show manager status and token
+
+  Usage:
     swarmy manager status
+  `);
+  process.exit(0);
+}
+
+function usageWorkerStart() {
+  console.log(`
+  swarmy worker start - Connect worker to a manager
+
+  Options:
+    --url URL          Manager URL (required)
+    --token TOKEN      Auth token (required)
+    --hostname NAME    Custom hostname identifier
+
+  Examples:
+    swarmy worker start --url http://192.168.1.10:5174 --token abc123
+    swarmy worker start --url http://manager:5174 --token abc123 --hostname gpu-node-01
+  `);
+  process.exit(0);
+}
 
-    swarmy worker start --url URL --token TOKEN [--hostname NAME]
+function usageWorkerStop() {
+  console.log(`
+  swarmy worker stop - Stop the worker
+
+  Usage:
     swarmy worker stop
-    swarmy worker restart --url URL --token TOKEN [--hostname NAME]
-    swarmy worker status
   `);
-  process.exit(1);
+  process.exit(0);
 }
 
-function parseFlag(flag) {
-  const idx = cliArgs.indexOf(flag);
-  if (idx === -1 || idx + 1 >= cliArgs.length) return undefined;
-  return cliArgs[idx + 1];
+function usageWorkerRestart() {
+  console.log(`
+  swarmy worker restart - Restart the worker
+
+  Options:
+    --url URL          Manager URL (required)
+    --token TOKEN      Auth token (required)
+    --hostname NAME    Custom hostname identifier
+
+  Examples:
+    swarmy worker restart --url http://192.168.1.10:5174 --token abc123
+  `);
+  process.exit(0);
 }
 
-if (!role || !action) usage();
+function usageWorkerStatus() {
+  console.log(`
+  swarmy worker status - Show worker status
+
+  Usage:
+    swarmy worker status
+  `);
+  process.exit(0);
+}
 
 function startManager() {
   const port = parseFlag("--port") ?? "5174";
@@ -189,44 +335,54 @@ function startWorker() {
 }
 
 if (role === "manager") {
+  if (action === "--help" || action === "-h") usageManager();
   switch (action) {
     case "start":
+      if (hasFlag("--help") || hasFlag("-h")) usageManagerStart();
       startManager();
       break;
     case "stop":
+      if (hasFlag("--help") || hasFlag("-h")) usageManagerStop();
       stopProcess("manager");
       break;
     case "restart":
+      if (hasFlag("--help") || hasFlag("-h")) usageManagerRestart();
       stopProcess("manager");
       setTimeout(startManager, 1000);
       break;
     case "status":
+      if (hasFlag("--help") || hasFlag("-h")) usageManagerStatus();
       showStatus("manager");
       if (getStatus("manager").running) {
         console.log(`Token: ${ensureToken()}`);
       }
       break;
     default:
-      usage();
+      usageManager();
   }
 } else if (role === "worker") {
+  if (action === "--help" || action === "-h") usageWorker();
   switch (action) {
     case "start":
+      if (hasFlag("--help") || hasFlag("-h")) usageWorkerStart();
       startWorker();
       break;
     case "stop":
+      if (hasFlag("--help") || hasFlag("-h")) usageWorkerStop();
       stopProcess("worker");
       break;
     case "restart":
+      if (hasFlag("--help") || hasFlag("-h")) usageWorkerRestart();
       stopProcess("worker");
       setTimeout(startWorker, 1000);
       break;
     case "status":
+      if (hasFlag("--help") || hasFlag("-h")) usageWorkerStatus();
       showStatus("worker");
       break;
     default:
-      usage();
+      usageWorker();
   }
 } else {
-  usage();
+  usageMain();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swarmy",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Distributed container management with browser-based VNC and terminal access",
   "type": "module",
   "bin": {