@gowelle/stint-agent 1.0.8 → 1.1.0

package/README.md

@@ -113,32 +113,30 @@ stint status
 
 ## Troubleshooting
 
-### "Not authenticated" error
+For comprehensive troubleshooting help, see the **[Troubleshooting Guide](docs/TROUBLESHOOTING.md)**.
 
-Run `stint login` to authenticate with your Stint account.
-
-### "Repository has uncommitted changes"
-
-The agent requires a clean repository to execute commits:
+### Quick Tips
 
+**"Not authenticated" error**
 ```bash
-git stash                  # Temporarily stash changes
-# or
-git add . && git commit -m "message"
+stint login
 ```
 
-### Daemon won't start
-
+**Daemon won't start**
 ```bash
 stint daemon status        # Check if already running
 stint daemon logs          # Check logs for errors
-stint daemon stop          # Stop first
-stint daemon start         # Then start again
+stint daemon restart       # Restart daemon
 ```
 
-### WebSocket connection issues
+**For detailed solutions**, including:
+- Connection issues (WebSocket, API, Circuit Breaker)
+- Daemon problems (crashes, autostart)
+- Authentication errors
+- Git operation failures
+- Platform-specific issues (Windows, macOS, Linux)
 
-Check your network connection and firewall settings.
+See the **[Troubleshooting Guide](docs/TROUBLESHOOTING.md)**.
 
 ## Logging
 

package/dist/{api-2MI5XBJX.js → api-YI2HWZGL.js}

@@ -1,6 +1,6 @@
 import {
   apiService
-} from "./chunk-5OKRSNU4.js";
+} from "./chunk-IAERVP6F.js";
 export {
   apiService
 };

package/dist/{chunk-5OKRSNU4.js → chunk-IAERVP6F.js}

@@ -254,7 +254,7 @@ var AuthServiceImpl = class {
       return null;
     }
     try {
-      const { apiService: apiService2 } = await import("./api-2MI5XBJX.js");
+      const { apiService: apiService2 } = await import("./api-YI2HWZGL.js");
       const user = await apiService2.getCurrentUser();
       logger.info("auth", `Token validated for user: ${user.email}`);
       return user;
@@ -273,10 +273,116 @@ var AuthServiceImpl = class {
 };
 var authService = new AuthServiceImpl();
 
+// src/utils/circuit-breaker.ts
+var CircuitBreaker = class {
+  constructor(options) {
+    this.options = options;
+    this.options.windowSize = options.windowSize || 6e4;
+  }
+  state = "CLOSED";
+  failures = 0;
+  successes = 0;
+  lastFailureTime = 0;
+  openedAt = 0;
+  failureTimestamps = [];
+  /**
+   * Execute an operation through the circuit breaker
+   */
+  async execute(operation, fallback) {
+    if (this.state === "OPEN") {
+      if (Date.now() - this.openedAt >= this.options.timeout) {
+        this.state = "HALF_OPEN";
+        this.successes = 0;
+      } else {
+        if (fallback) {
+          return fallback();
+        }
+        throw new Error("Circuit breaker is OPEN - service unavailable");
+      }
+    }
+    try {
+      const result = await operation();
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      this.onFailure();
+      throw error;
+    }
+  }
+  /**
+   * Handle successful operation
+   */
+  onSuccess() {
+    this.failures = 0;
+    if (this.state === "HALF_OPEN") {
+      this.successes++;
+      if (this.successes >= this.options.successThreshold) {
+        this.state = "CLOSED";
+        this.successes = 0;
+        this.failureTimestamps = [];
+      }
+    }
+  }
+  /**
+   * Handle failed operation
+   */
+  onFailure() {
+    this.lastFailureTime = Date.now();
+    this.failureTimestamps.push(this.lastFailureTime);
+    const windowStart = this.lastFailureTime - this.options.windowSize;
+    this.failureTimestamps = this.failureTimestamps.filter((ts) => ts > windowStart);
+    this.failures = this.failureTimestamps.length;
+    if (this.state === "HALF_OPEN") {
+      this.state = "OPEN";
+      this.openedAt = Date.now();
+      this.successes = 0;
+    } else if (this.state === "CLOSED") {
+      if (this.failures >= this.options.failureThreshold) {
+        this.state = "OPEN";
+        this.openedAt = Date.now();
+      }
+    }
+  }
+  /**
+   * Get current state
+   */
+  getState() {
+    return this.state;
+  }
+  /**
+   * Get failure count in current window
+   */
+  getFailureCount() {
+    return this.failures;
+  }
+  /**
+   * Reset the circuit breaker to CLOSED state
+   */
+  reset() {
+    this.state = "CLOSED";
+    this.failures = 0;
+    this.successes = 0;
+    this.failureTimestamps = [];
+  }
+};
+
 // src/services/api.ts
-var AGENT_VERSION = "1.0.8";
+var AGENT_VERSION = "1.1.0";
 var ApiServiceImpl = class {
   sessionId = null;
+  circuitBreaker = new CircuitBreaker({
+    failureThreshold: 5,
+    successThreshold: 2,
+    timeout: 3e4,
+    // 30s before trying half-open
+    windowSize: 6e4
+    // 60s failure window
+  });
+  /**
+   * Get authentication headers for API requests
+   * @returns Headers object with Authorization and Content-Type
+   * @throws Error if no authentication token is found
+   */
   async getHeaders() {
     const token = await authService.getToken();
     if (!token) {
@@ -287,29 +393,43 @@ var ApiServiceImpl = class {
       "Content-Type": "application/json"
     };
   }
+  /**
+   * Make an HTTP request to the API with circuit breaker protection
+   * @param endpoint - API endpoint path (e.g., '/api/user')
+   * @param options - Fetch options (method, body, headers, etc.)
+   * @returns Parsed JSON response
+   * @throws Error if request fails or circuit breaker is open
+   */
   async request(endpoint, options = {}) {
     const url = `${config.getApiUrl()}${endpoint}`;
     const headers = await this.getHeaders();
-    try {
-      const response = await fetch(url, {
-        ...options,
-        headers: {
-          ...headers,
-          ...options.headers
+    return this.circuitBreaker.execute(async () => {
+      try {
+        const response = await fetch(url, {
+          ...options,
+          headers: {
+            ...headers,
+            ...options.headers
+          }
+        });
+        if (!response.ok) {
+          const errorText = await response.text();
+          throw new Error(`API request failed: ${response.status} ${errorText}`);
         }
-      });
-      if (!response.ok) {
-        const errorText = await response.text();
-        throw new Error(`API request failed: ${response.status} ${errorText}`);
+        return await response.json();
+      } catch (error) {
+        logger.error("api", `Request to ${endpoint} failed`, error);
+        throw error;
       }
-      return await response.json();
-    } catch (error) {
-      logger.error("api", `Request to ${endpoint} failed`, error);
-      throw error;
-    }
+    });
   }
   /**
    * Retry wrapper with exponential backoff
+   * @param operation - Async operation to retry
+   * @param operationName - Name for logging
+   * @param maxRetries - Maximum number of retry attempts (default: 3)
+   * @returns Result of the operation
+   * @throws Last error if all retries fail
    */
   async withRetry(operation, operationName, maxRetries = 3) {
     let lastError;
@@ -332,6 +452,11 @@ var ApiServiceImpl = class {
     }
     throw lastError;
   }
+  /**
+   * Connect agent session to the API
+   * @returns Agent session data including session ID
+   * @throws Error if connection fails
+   */
   async connect() {
     logger.info("api", "Connecting agent session...");
     const os4 = `${process.platform}-${process.arch}`;
@@ -351,6 +476,10 @@ var ApiServiceImpl = class {
       return session;
     }, "Connect");
   }
+  /**
+   * Disconnect agent session from the API
+   * @param reason - Optional reason for disconnection
+   */
   async disconnect(reason) {
     if (!this.sessionId) {
       return;
@@ -366,6 +495,10 @@ var ApiServiceImpl = class {
     this.sessionId = null;
     logger.success("api", "Agent session disconnected");
   }
+  /**
+   * Send heartbeat to keep session alive
+   * @throws Error if no active session
+   */
   async heartbeat() {
     if (!this.sessionId) {
       throw new Error("No active session");
@@ -380,6 +513,11 @@ var ApiServiceImpl = class {
       logger.debug("api", "Heartbeat sent");
     }, "Heartbeat");
   }
+  /**
+   * Get pending commits for a project
+   * @param projectId - Project ID
+   * @returns Array of pending commits
+   */
   async getPendingCommits(projectId) {
     logger.info("api", `Fetching pending commits for project ${projectId}`);
     const response = await this.request(
@@ -395,6 +533,12 @@ var ApiServiceImpl = class {
     logger.info("api", `Found ${commits.length} pending commits`);
     return commits;
   }
+  /**
+   * Mark a commit as successfully executed
+   * @param commitId - Commit ID
+   * @param sha - Git commit SHA
+   * @returns Updated commit data
+   */
   async markCommitExecuted(commitId, sha) {
     logger.info("api", `Marking commit ${commitId} as executed (SHA: ${sha})`);
     return this.withRetry(async () => {
@@ -420,6 +564,11 @@ var ApiServiceImpl = class {
       return commit;
     }, "Mark commit executed");
   }
+  /**
+   * Mark a commit as failed
+   * @param commitId - Commit ID
+   * @param error - Error message
+   */
   async markCommitFailed(commitId, error) {
     logger.error("api", `Marking commit ${commitId} as failed: ${error}`);
     await this.withRetry(async () => {
@@ -429,6 +578,11 @@ var ApiServiceImpl = class {
       });
     }, "Mark commit failed");
   }
+  /**
+   * Sync project repository information with the API
+   * @param projectId - Project ID
+   * @param data - Repository information (path, remote URL, branches)
+   */
   async syncProject(projectId, data) {
     logger.info("api", `Syncing project ${projectId}`);
     await this.withRetry(async () => {

package/dist/{chunk-56UZEICO.js → chunk-OHOFKJL7.js}

@@ -2,7 +2,7 @@ import {
   apiService,
   config,
   logger
-} from "./chunk-5OKRSNU4.js";
+} from "./chunk-IAERVP6F.js";
 
 // src/utils/process.ts
 import fs from "fs";
@@ -104,6 +104,11 @@ var GitServiceImpl = class {
   getGit(path3) {
     return simpleGit(path3);
   }
+  /**
+   * Check if a directory is a git repository
+   * @param path - Directory path to check
+   * @returns True if directory is a git repository
+   */
   async isRepo(path3) {
     try {
       const git = this.getGit(path3);
@@ -113,6 +118,12 @@ var GitServiceImpl = class {
       return false;
     }
   }
+  /**
+   * Get comprehensive repository information
+   * @param path - Repository path
+   * @returns Repository info including branches, status, and last commit
+   * @throws Error if not a valid repository or no commits found
+   */
   async getRepoInfo(path3) {
     try {
       const git = this.getGit(path3);

package/dist/daemon/runner.js

@@ -5,13 +5,13 @@ import {
   projectService,
   removePidFile,
   writePidFile
-} from "../chunk-56UZEICO.js";
+} from "../chunk-OHOFKJL7.js";
 import {
   apiService,
   authService,
   config,
   logger
-} from "../chunk-5OKRSNU4.js";
+} from "../chunk-IAERVP6F.js";
 
 // src/daemon/runner.ts
 import "dotenv/config";
@@ -33,6 +33,10 @@ var WebSocketServiceImpl = class {
   disconnectHandlers = [];
   agentDisconnectedHandlers = [];
   syncRequestedHandlers = [];
+  /**
+   * Connect to the WebSocket server
+   * @throws Error if connection fails or no auth token available
+   */
   async connect() {
     try {
       const token = await authService.getToken();
@@ -71,6 +75,10 @@ var WebSocketServiceImpl = class {
       throw error;
     }
   }
+  /**
+   * Disconnect from the WebSocket server
+   * Prevents automatic reconnection
+   */
   disconnect() {
     this.isManualDisconnect = true;
     if (this.reconnectTimer) {
@@ -91,9 +99,17 @@ var WebSocketServiceImpl = class {
       logger.info("websocket", "WebSocket disconnected");
     }
   }
+  /**
+   * Check if WebSocket is currently connected
+   * @returns True if connected and ready
+   */
   isConnected() {
     return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
   }
+  /**
+   * Subscribe to user-specific channel for real-time updates
+   * @param userId - User ID to subscribe to
+   */
   subscribeToUserChannel(userId) {
     this.userId = userId;
     if (!this.isConnected()) {
@@ -109,6 +125,10 @@ var WebSocketServiceImpl = class {
       }
     });
   }
+  /**
+   * Register handler for commit approved events
+   * @param handler - Callback function
+   */
   onCommitApproved(handler) {
     this.commitApprovedHandlers.push(handler);
   }
@@ -214,10 +234,16 @@ var WebSocketServiceImpl = class {
       logger.error("websocket", "Max reconnection attempts reached");
     }
   }
+  /**
+   * Get reconnect delay with exponential backoff and jitter
+   * Jitter prevents thundering herd problem when many clients reconnect simultaneously
+   */
   getReconnectDelay() {
     const delays = [1e3, 2e3, 4e3, 8e3, 16e3, 3e4];
     const index = Math.min(this.reconnectAttempts, delays.length - 1);
-    return delays[index];
+    const baseDelay = delays[index];
+    const jitter = baseDelay * (Math.random() * 0.3);
+    return Math.floor(baseDelay + jitter);
   }
 };
 var websocketService = new WebSocketServiceImpl();

package/dist/index.js

@@ -8,13 +8,13 @@ import {
   projectService,
   spawnDetached,
   validatePidFile
-} from "./chunk-56UZEICO.js";
+} from "./chunk-OHOFKJL7.js";
 import {
   apiService,
   authService,
   config,
   logger
-} from "./chunk-5OKRSNU4.js";
+} from "./chunk-IAERVP6F.js";
 
 // src/index.ts
 import "dotenv/config";
@@ -1328,7 +1328,7 @@ Current version: ${currentVersion}`));
 }
 
 // src/index.ts
-var AGENT_VERSION = "1.0.8";
+var AGENT_VERSION = "1.1.0";
 var program = new Command();
 program.name("stint").description("Stint Agent - Local daemon for Stint Project Assistant").version(AGENT_VERSION, "-v, --version", "output the current version").addHelpText("after", `
 ${chalk12.bold("Examples:")}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gowelle/stint-agent",
-  "version": "1.0.8",
+  "version": "1.1.0",
   "description": "Local agent for Stint - Project Assistant",
   "author": "Gowelle John <gowelle.john@icloud.com>",
   "license": "MIT",
@@ -54,6 +54,7 @@
     "@types/ws": "^8.5.10",
     "@typescript-eslint/eslint-plugin": "^8.50.0",
     "@typescript-eslint/parser": "^8.50.0",
+    "@vitest/coverage-v8": "^4.0.16",
     "eslint": "^8.56.0",
     "tsup": "^8.0.1",
     "typescript": "^5.3.3",