@gowelle/stint-agent 1.0.7 → 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-DA6X5ZWT.js → api-YI2HWZGL.js}

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

package/dist/{chunk-DPKCS26C.js → chunk-IAERVP6F.js}

@@ -254,7 +254,7 @@ var AuthServiceImpl = class {
       return null;
     }
     try {
-      const { apiService: apiService2 } = await import("./api-DA6X5ZWT.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.7";
+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-EEO2GKXF.js → chunk-OHOFKJL7.js}

@@ -2,7 +2,7 @@ import {
   apiService,
   config,
   logger
-} from "./chunk-DPKCS26C.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);
@@ -229,6 +240,15 @@ var GitServiceImpl = class {
       throw new Error(`Failed to get git status: ${error.message}`);
     }
   }
+  async getRepoRoot(path3) {
+    try {
+      const git = this.getGit(path3);
+      const root = await git.revparse(["--show-toplevel"]);
+      return root.trim();
+    } catch {
+      return null;
+    }
+  }
 };
 var gitService = new GitServiceImpl();
 
@@ -238,16 +258,20 @@ var ProjectServiceImpl = class {
   async linkProject(projectPath, projectId) {
     try {
       const absolutePath = path2.resolve(projectPath);
-      const isRepo = await gitService.isRepo(absolutePath);
-      if (!isRepo) {
-        throw new Error(`${absolutePath} is not a git repository`);
+      const repoRoot = await gitService.getRepoRoot(absolutePath);
+      const linkPath = repoRoot || absolutePath;
+      if (!repoRoot) {
+        const isRepo = await gitService.isRepo(absolutePath);
+        if (!isRepo) {
+          throw new Error(`${absolutePath} is not a git repository`);
+        }
       }
       const linkedProject = {
         projectId,
         linkedAt: (/* @__PURE__ */ new Date()).toISOString()
       };
-      config.setProject(absolutePath, linkedProject);
-      logger.success("project", `Linked ${absolutePath} to project ${projectId}`);
+      config.setProject(linkPath, linkedProject);
+      logger.success("project", `Linked ${linkPath} must be to project ${projectId}`);
     } catch (error) {
       logger.error("project", "Failed to link project", error);
       throw error;
@@ -256,20 +280,29 @@ var ProjectServiceImpl = class {
   async unlinkProject(projectPath) {
     try {
       const absolutePath = path2.resolve(projectPath);
-      const linkedProject = this.getLinkedProject(absolutePath);
+      const repoRoot = await gitService.getRepoRoot(absolutePath);
+      const lookupPath = repoRoot || absolutePath;
+      const linkedProject = config.getProject(lookupPath);
       if (!linkedProject) {
         throw new Error(`${absolutePath} is not linked to any project`);
       }
-      config.removeProject(absolutePath);
-      logger.success("project", `Unlinked ${absolutePath}`);
+      config.removeProject(lookupPath);
+      logger.success("project", `Unlinked ${lookupPath}`);
     } catch (error) {
       logger.error("project", "Failed to unlink project", error);
       throw error;
     }
   }
-  getLinkedProject(projectPath) {
+  async getLinkedProject(projectPath) {
     const absolutePath = path2.resolve(projectPath);
-    return config.getProject(absolutePath) || null;
+    let project = config.getProject(absolutePath);
+    if (project) return project;
+    const repoRoot = await gitService.getRepoRoot(absolutePath);
+    if (repoRoot) {
+      project = config.getProject(repoRoot);
+      if (project) return project;
+    }
+    return null;
   }
   getAllLinkedProjects() {
     return config.getProjects();

package/dist/daemon/runner.js

@@ -5,13 +5,13 @@ import {
   projectService,
   removePidFile,
   writePidFile
-} from "../chunk-EEO2GKXF.js";
+} from "../chunk-OHOFKJL7.js";
 import {
   apiService,
   authService,
   config,
   logger
-} from "../chunk-DPKCS26C.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-EEO2GKXF.js";
+} from "./chunk-OHOFKJL7.js";
 import {
   apiService,
   authService,
   config,
   logger
-} from "./chunk-DPKCS26C.js";
+} from "./chunk-IAERVP6F.js";
 
 // src/index.ts
 import "dotenv/config";
@@ -456,7 +456,7 @@ function registerLinkCommand(program2) {
     const spinner = ora4("Checking directory...").start();
     try {
       const cwd = process2.cwd();
-      const existingLink = projectService.getLinkedProject(cwd);
+      const existingLink = await projectService.getLinkedProject(cwd);
       if (existingLink) {
         spinner.warn("Directory already linked");
         console.log(chalk4.yellow(`
@@ -562,7 +562,7 @@ function registerUnlinkCommand(program2) {
     const spinner = ora5("Checking directory...").start();
     try {
       const cwd = process3.cwd();
-      const linkedProject = projectService.getLinkedProject(cwd);
+      const linkedProject = await projectService.getLinkedProject(cwd);
       if (!linkedProject) {
         spinner.info("Not linked");
         console.log(chalk5.yellow("\n\u26A0 This directory is not linked to any project.\n"));
@@ -613,7 +613,7 @@ function registerStatusCommand(program2) {
     const spinner = ora6("Gathering status...").start();
     try {
       const cwd = process4.cwd();
-      const linkedProject = projectService.getLinkedProject(cwd);
+      const linkedProject = await projectService.getLinkedProject(cwd);
       const user = await authService.validateToken();
       spinner.stop();
       console.log(chalk6.blue("\n\u{1F4E6} Project Status:"));
@@ -698,7 +698,7 @@ function registerSyncCommand(program2) {
     const spinner = ora7("Checking directory...").start();
     try {
       const cwd = process5.cwd();
-      const linkedProject = projectService.getLinkedProject(cwd);
+      const linkedProject = await projectService.getLinkedProject(cwd);
       if (!linkedProject) {
         spinner.fail("Not linked");
         console.log(chalk7.yellow("\n\u26A0 This directory is not linked to any project."));
@@ -937,7 +937,7 @@ function registerCommitCommands(program2) {
     const spinner = ora9("Loading pending commits...").start();
     try {
       const cwd = process6.cwd();
-      const linkedProject = projectService.getLinkedProject(cwd);
+      const linkedProject = await projectService.getLinkedProject(cwd);
       if (!linkedProject) {
         spinner.fail("Not linked");
         console.log(chalk9.yellow("\n\u26A0 This directory is not linked to any project."));
@@ -979,7 +979,7 @@ function registerCommitCommands(program2) {
     const spinner = ora9("Checking repository status...").start();
     try {
       const cwd = process6.cwd();
-      const linkedProject = projectService.getLinkedProject(cwd);
+      const linkedProject = await projectService.getLinkedProject(cwd);
       if (!linkedProject) {
         spinner.fail("Not linked");
         console.log(chalk9.yellow("\n\u26A0 This directory is not linked to any project."));
@@ -1328,9 +1328,9 @@ Current version: ${currentVersion}`));
 }
 
 // src/index.ts
-var AGENT_VERSION = "1.0.7";
+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, -V, --version", "output the current version").addHelpText("after", `
+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:")}
   ${chalk12.cyan("$")} stint login                 ${chalk12.gray("# Authenticate with Stint")}
   ${chalk12.cyan("$")} stint install               ${chalk12.gray("# Install agent to run on startup")}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gowelle/stint-agent",
-  "version": "1.0.7",
+  "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",