k6lab-agent 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,97 @@
+# 🚀 k6lab-agent
+
+> The high-performance, local load-testing execution runner for the **K6 Lab** platform.
+
+`k6lab-agent` is a lightweight, globally linked command-line utility that bridges your local environment with the K6 Lab dashboard. By utilizing this local agent, K6 Lab runs in **Agent-Only Mode**, running heavy stress tests directly on your laptop with zero-overhead server processing, while synchronizing live telemetry and logs in real-time.
+
+---
+
+## 📦 Features
+
+* **Local k6 Execution**: Spawns native, lightning-fast `k6` binaries directly on your machine.
+* **Real-Time Log Streaming**: Streams terminal output (`stdout`/`stderr`) live to your K6 Lab dashboard cockpit.
+* **Atomically Queued Runs**: Automatically polls your MongoDB backend queues and executes runs chronologically.
+* **Heartbeat Synchronizer**: Periodically signals connection status (online/offline) to prevent diagnostic dropouts.
+* **Zero Secrets Exposure**: Kept completely safe—no database credentials or private environment variables are stored in the agent.
+
+---
+
+## 🛠️ Installation
+
+Ensure you have [Node.js](https://nodejs.org/) (v16+) and the [k6 load testing tool](https://k6.io/docs/get-started/installation/) installed locally.
+
+### 1. Install k6 (Native Binary)
+* **macOS** (via Homebrew):
+  ```bash
+  brew install k6
+  ```
+* **Windows** (via Chocolatey):
+  ```powershell
+  choco install k6
+  ```
+* **Linux** (via Debian/Ubuntu):
+  ```bash
+  sudo gpg --no-default-keyring --keyring /usr/share/keyrings/k6-archive-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C5D53F5675C117B8
+  echo "deb [signed-by=/usr/share/keyrings/k6-archive-keyring.gpg] https://dl.k6.io/deb stable main" | sudo tee /etc/apt/sources.list.d/k6.list
+  sudo apt-get update
+  sudo apt-get install k6
+  ```
+
+### 2. Install the Agent CLI Globally
+Install the package directly from the public npm registry:
+```bash
+npm install -g k6lab-agent
+```
+
+---
+
+## 🚀 Getting Started
+
+To link and run your agent, follow these quick steps:
+
+### Step 1: Login with your API Token
+Retrieve your unique agent login token from your K6 Lab dashboard panel, and authenticate:
+```bash
+k6lab-agent login k6lab_agent_your_unique_dashboard_token
+```
+
+### Step 2: Start the Agent runner
+Start the runner loop. The agent will connect, start emitting 5-second heartbeats to display as "Online" on your dashboard, and listen for new stress tests:
+```bash
+k6lab-agent start
+```
+
+*Leave this terminal window open. As soon as you click **"Dispatch Load Test Run"** on the K6 Lab configurator, the agent will instantly catch the job, execute k6, and feed live console logs back to your screen!*
+
+---
+
+## 💻 CLI Command Reference
+
+| Command | Description |
+| :--- | :--- |
+| `k6lab-agent login <token>` | Saves your API credentials and registers your Mac/PC with the backend server. |
+| `k6lab-agent start` | Connects the active agent, initiates heartbeats, and polls for pending dashboard runs. |
+| `k6lab-agent status` | Displays the current connection and login configurations. |
+| `k6lab-agent logout` | Revokes the current agent token and clears credentials from your machine. |
+
+---
+
+## 📂 Configuration Storage
+
+The agent securely stores local configuration parameters inside a hidden directory in your user home folder:
+* **Storage Location**: `~/.k6lab/config.json`
+* **Contents**:
+  ```json
+  {
+    "token": "k6lab_agent_your_token_hash",
+    "apiUrl": "http://localhost:8000/api"
+  }
+  ```
+
+---
+
+## 🔐 Security & Privacy
+
+* **Strict Encryption**: Tokens are cryptographically matched on the Mongoose backend using one-way SHA-256 hashes.
+* **Target URLs**: All network traffic generated during stress runs goes directly from your local machine to the target URL. 
+* **Self-Contained**: The agent only reads the dynamically generated temporary k6 test scripts in `~/.k6lab/jobs/` and has no access to other filesystem paths.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "k6lab-agent",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Local agent for K6 Lab load testing",
   "type": "module",
   "bin": {

package/src/commands/start.js

@@ -1,4 +1,5 @@
 import fs from "fs-extra";
+import path from "path";
 import { checkK6Installed } from "../services/k6Checker.js";
 import {
   sendHeartbeat,
@@ -86,8 +87,11 @@ export async function start() {
           }
         }, 2000);
 
+        let scriptPath = null;
         try {
-          const { scriptPath, summaryPath, logsPath } = await createK6Script(job);
+          const scriptDetails = await createK6Script(job);
+          scriptPath = scriptDetails.scriptPath;
+          const { summaryPath, logsPath } = scriptDetails;
 
           const runResult = await runK6(scriptPath, job, logsPath);
 
@@ -133,6 +137,12 @@ export async function start() {
                 console.log("");
                 console.log("Waiting for jobs...");
                 console.log("");
+                
+                if (scriptPath) {
+                  try {
+                    await fs.remove(path.dirname(scriptPath));
+                  } catch (cleanErr) {}
+                }
                 continue;
               }
             } catch (statusErr) {
@@ -154,6 +164,13 @@ export async function start() {
 
           console.log("Waiting for jobs...");
           console.log("");
+        } finally {
+          // 🧹 Clean up local job folder on success or error
+          if (scriptPath) {
+            try {
+              await fs.remove(path.dirname(scriptPath));
+            } catch (cleanErr) {}
+          }
         }
       } catch (err) {
         console.error("Agent connection error:", err.message);