@gowelle/stint-agent 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Gowelle John
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# Stint Agent
+
+[![npm version](https://img.shields.io/npm/v/@gowelle/stint-agent.svg)](https://www.npmjs.com/package/@gowelle/stint-agent)
+[![npm downloads](https://img.shields.io/npm/dm/@gowelle/stint-agent.svg)](https://www.npmjs.com/package/@gowelle/stint-agent)
+[![CI](https://github.com/gowelle/stint-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/gowelle/stint-agent/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
+
+The official CLI agent for [Stint](https://stint.codes) — a lightweight daemon that bridges the Stint web app and your local git repositories, enabling automatic commit execution and real-time repo syncing.
+
+## Features
+
+- 🔐 Secure authentication with OAuth
+- 🔄 Real-time WebSocket connection to Stint
+- 📦 Automatic commit execution
+- 🔍 Repository status syncing
+- 🖥️ Background daemon process
+- 📝 Comprehensive logging
+
+## Installation
+
+```bash
+npm install -g @gowelle/stint-agent
+# or
+pnpm add -g @gowelle/stint-agent
+```
+
+## Quick Start
+
+```bash
+# Authenticate with Stint
+stint login
+
+# Check your authentication status
+stint whoami
+
+# Link a project
+cd /path/to/your/project
+stint link
+
+# Start the daemon
+stint daemon start
+
+# Check daemon status
+stint daemon status
+```
+
+## Commands
+
+### Authentication
+
+| Command | Description |
+|---------|-------------|
+| `stint login` | Authenticate with Stint (opens browser for OAuth) |
+| `stint logout` | Remove stored credentials |
+| `stint whoami` | Show current user and machine information |
+
+### Daemon
+
+| Command | Description |
+|---------|-------------|
+| `stint daemon start` | Start background daemon |
+| `stint daemon stop` | Stop daemon gracefully |
+| `stint daemon status` | Check if daemon is running |
+| `stint daemon logs [--lines N]` | View daemon logs (default: 50 lines) |
+| `stint daemon restart` | Restart the daemon |
+
+### Project Management
+
+| Command | Description |
+|---------|-------------|
+| `stint link` | Link current directory to a Stint project |
+| `stint unlink [--force]` | Remove project link |
+| `stint status` | Show project, git, auth, and daemon status |
+| `stint sync` | Manually sync repository information to server |
+
+### Commit Operations
+
+| Command | Description |
+|---------|-------------|
+| `stint commits` | List pending commits for this repository |
+| `stint commit <id>` | Execute a specific pending commit |
+
+## Complete Workflow
+
+```bash
+# 1. Install and authenticate
+npm install -g @gowelle/stint-agent
+stint login
+
+# 2. Link your project
+cd /path/to/your/project
+stint link
+
+# 3. Start the daemon
+stint daemon start
+
+# 4. Check status
+stint status
+
+# Now commits approved in the web app will execute automatically!
+```
+
+## Troubleshooting
+
+### "Not authenticated" error
+
+Run `stint login` to authenticate with your Stint account.
+
+### "Repository has uncommitted changes"
+
+The agent requires a clean repository to execute commits:
+
+```bash
+git stash                  # Temporarily stash changes
+# or
+git add . && git commit -m "message"
+```
+
+### 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
+```
+
+### WebSocket connection issues
+
+Check your network connection and firewall settings.
+
+## Logging
+
+Logs are stored in your system's config directory:
+
+| Platform | Log Location |
+|----------|--------------|
+| **macOS** | `~/.config/stint/logs/` |
+| **Linux** | `~/.config/stint/logs/` |
+| **Windows** | `%USERPROFILE%\.config\stint\logs\` |
+
+Log files:
+- `agent.log` - General CLI operations
+- `daemon.log` - Daemon process logs
+- `error.log` - Error details
+
+## Development
+
+```bash
+git clone https://github.com/gowelle/stint-agent.git
+cd stint-agent
+pnpm install
+pnpm build
+pnpm dev    # Watch mode
+```
+
+## Security
+
+- Tokens are encrypted at rest using machine-specific keys
+- All API communication uses HTTPS
+- WebSocket connections are authenticated
+- Git operations are restricted to linked directories
+
+## License
+
+MIT © [Gowelle John](https://github.com/gowelle)
+
+## Support
+
+For issues and questions, please [open an issue](https://github.com/gowelle/stint-agent/issues).

package/dist/api-K3EUONWR.js

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

package/dist/chunk-5DWSNHS6.js

@@ -0,0 +1,448 @@
+// src/services/api.ts
+import { createRequire } from "module";
+
+// src/utils/config.ts
+import Conf from "conf";
+import { randomUUID } from "crypto";
+import os from "os";
+var DEFAULT_CONFIG = {
+  apiUrl: "https://stint.codes",
+  wsUrl: "wss://stint.codes/reverb",
+  reverbAppKey: "wtn6tu6lirfv6yflujk7",
+  projects: {}
+};
+var ConfigManager = class {
+  conf;
+  constructor() {
+    this.conf = new Conf({
+      projectName: "stint",
+      defaults: {
+        ...DEFAULT_CONFIG,
+        machineId: randomUUID(),
+        machineName: os.hostname()
+      }
+    });
+  }
+  get(key) {
+    return this.conf.get(key);
+  }
+  set(key, value) {
+    this.conf.set(key, value);
+  }
+  getAll() {
+    return this.conf.store;
+  }
+  clear() {
+    this.conf.clear();
+  }
+  // Token management
+  getToken() {
+    return this.conf.get("token");
+  }
+  setToken(token) {
+    this.conf.set("token", token);
+  }
+  clearToken() {
+    this.conf.delete("token");
+  }
+  // Machine info
+  getMachineId() {
+    return this.conf.get("machineId");
+  }
+  getMachineName() {
+    return this.conf.get("machineName");
+  }
+  // Project management
+  getProjects() {
+    return this.conf.get("projects") || {};
+  }
+  getProject(path2) {
+    const projects = this.getProjects();
+    return projects[path2];
+  }
+  setProject(path2, project) {
+    const projects = this.getProjects();
+    projects[path2] = project;
+    this.conf.set("projects", projects);
+  }
+  removeProject(path2) {
+    const projects = this.getProjects();
+    delete projects[path2];
+    this.conf.set("projects", projects);
+  }
+  // API URLs
+  getApiUrl() {
+    return this.conf.get("apiUrl");
+  }
+  getWsUrl() {
+    const environment = this.getEnvironment();
+    const reverbAppKey = this.getReverbAppKey();
+    let baseUrl;
+    if (environment === "development") {
+      baseUrl = "ws://localhost:8080";
+    } else {
+      baseUrl = this.conf.get("wsUrl") || "wss://stint.codes/reverb";
+    }
+    if (reverbAppKey && reverbAppKey.trim() !== "") {
+      const cleanBaseUrl2 = baseUrl.replace(/\/$/, "");
+      const baseWithoutReverb = cleanBaseUrl2.replace(/\/reverb$/, "");
+      return `${baseWithoutReverb}/app/${reverbAppKey}`;
+    }
+    const cleanBaseUrl = baseUrl.replace(/\/$/, "");
+    if (!cleanBaseUrl.includes("/reverb")) {
+      return `${cleanBaseUrl}/reverb`;
+    }
+    return cleanBaseUrl;
+  }
+  // Environment management
+  getEnvironment() {
+    const configEnv = this.conf.get("environment");
+    if (configEnv === "development" || configEnv === "production") {
+      return configEnv;
+    }
+    const nodeEnv = process.env.NODE_ENV;
+    if (nodeEnv === "development" || nodeEnv === "dev") {
+      return "development";
+    }
+    return "production";
+  }
+  setEnvironment(environment) {
+    this.conf.set("environment", environment);
+  }
+  // Reverb App Key management
+  getReverbAppKey() {
+    return process.env.REVERB_APP_KEY || process.env.STINT_REVERB_APP_KEY || this.conf.get("reverbAppKey");
+  }
+  setReverbAppKey(reverbAppKey) {
+    this.conf.set("reverbAppKey", reverbAppKey);
+  }
+};
+var config = new ConfigManager();
+
+// src/utils/crypto.ts
+import crypto from "crypto";
+import os2 from "os";
+function getMachineKey() {
+  const machineInfo = `${os2.hostname()}-${os2.platform()}-${os2.arch()}`;
+  return crypto.createHash("sha256").update(machineInfo).digest();
+}
+var ALGORITHM = "aes-256-gcm";
+var IV_LENGTH = 16;
+var AUTH_TAG_LENGTH = 16;
+function encrypt(text) {
+  const key = getMachineKey();
+  const iv = crypto.randomBytes(IV_LENGTH);
+  const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+  let encrypted = cipher.update(text, "utf8", "hex");
+  encrypted += cipher.final("hex");
+  const authTag = cipher.getAuthTag();
+  return iv.toString("hex") + authTag.toString("hex") + encrypted;
+}
+function decrypt(encryptedText) {
+  const key = getMachineKey();
+  const iv = Buffer.from(encryptedText.slice(0, IV_LENGTH * 2), "hex");
+  const authTag = Buffer.from(
+    encryptedText.slice(IV_LENGTH * 2, (IV_LENGTH + AUTH_TAG_LENGTH) * 2),
+    "hex"
+  );
+  const encrypted = encryptedText.slice((IV_LENGTH + AUTH_TAG_LENGTH) * 2);
+  const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
+  decipher.setAuthTag(authTag);
+  let decrypted = decipher.update(encrypted, "hex", "utf8");
+  decrypted += decipher.final("utf8");
+  return decrypted;
+}
+
+// src/utils/logger.ts
+import fs from "fs";
+import path from "path";
+import os3 from "os";
+var LOG_DIR = path.join(os3.homedir(), ".config", "stint", "logs");
+var AGENT_LOG = path.join(LOG_DIR, "agent.log");
+var ERROR_LOG = path.join(LOG_DIR, "error.log");
+var MAX_LOG_SIZE = 10 * 1024 * 1024;
+var MAX_LOG_FILES = 7;
+var Logger = class {
+  ensureLogDir() {
+    if (!fs.existsSync(LOG_DIR)) {
+      fs.mkdirSync(LOG_DIR, { recursive: true });
+    }
+  }
+  rotateLog(logFile) {
+    if (!fs.existsSync(logFile)) return;
+    const stats = fs.statSync(logFile);
+    if (stats.size < MAX_LOG_SIZE) return;
+    for (let i = MAX_LOG_FILES - 1; i > 0; i--) {
+      const oldFile = `${logFile}.${i}`;
+      const newFile = `${logFile}.${i + 1}`;
+      if (fs.existsSync(oldFile)) {
+        if (i === MAX_LOG_FILES - 1) {
+          fs.unlinkSync(oldFile);
+        } else {
+          fs.renameSync(oldFile, newFile);
+        }
+      }
+    }
+    fs.renameSync(logFile, `${logFile}.1`);
+  }
+  writeLog(level, category, message, logFile) {
+    this.ensureLogDir();
+    this.rotateLog(logFile);
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    const logLine = `[${timestamp}] ${level.padEnd(5)} [${category}] ${message}
+`;
+    fs.appendFileSync(logFile, logLine);
+  }
+  info(category, message) {
+    this.writeLog("INFO", category, message, AGENT_LOG);
+    console.log(`\u2139 [${category}] ${message}`);
+  }
+  warn(category, message) {
+    this.writeLog("WARN", category, message, AGENT_LOG);
+    console.warn(`\u26A0 [${category}] ${message}`);
+  }
+  error(category, message, error) {
+    const fullMessage = error ? `${message}: ${error.message}` : message;
+    this.writeLog("ERROR", category, fullMessage, ERROR_LOG);
+    this.writeLog("ERROR", category, fullMessage, AGENT_LOG);
+    console.error(`\u2716 [${category}] ${fullMessage}`);
+    if (error?.stack) {
+      this.writeLog("ERROR", category, error.stack, ERROR_LOG);
+    }
+  }
+  debug(category, message) {
+    if (process.env.DEBUG) {
+      this.writeLog("DEBUG", category, message, AGENT_LOG);
+      console.debug(`\u{1F41B} [${category}] ${message}`);
+    }
+  }
+  success(category, message) {
+    this.writeLog("INFO", category, message, AGENT_LOG);
+    console.log(`\u2713 [${category}] ${message}`);
+  }
+};
+var logger = new Logger();
+
+// src/services/auth.ts
+var AuthServiceImpl = class {
+  async saveToken(token) {
+    try {
+      const encryptedToken = encrypt(token);
+      config.setToken(encryptedToken);
+      logger.info("auth", "Token saved successfully");
+    } catch (error) {
+      logger.error("auth", "Failed to save token", error);
+      throw error;
+    }
+  }
+  async getToken() {
+    try {
+      const encryptedToken = config.getToken();
+      if (!encryptedToken) {
+        return null;
+      }
+      return decrypt(encryptedToken);
+    } catch (error) {
+      logger.error("auth", "Failed to decrypt token", error);
+      return null;
+    }
+  }
+  async clearToken() {
+    config.clearToken();
+    logger.info("auth", "Token cleared");
+  }
+  async validateToken() {
+    const token = await this.getToken();
+    if (!token) {
+      return null;
+    }
+    try {
+      const { apiService: apiService2 } = await import("./api-K3EUONWR.js");
+      const user = await apiService2.getCurrentUser();
+      logger.info("auth", `Token validated for user: ${user.email}`);
+      return user;
+    } catch (error) {
+      logger.warn("auth", "Token validation failed");
+      logger.error("auth", "Failed to validate token", error);
+      return null;
+    }
+  }
+  getMachineId() {
+    return config.getMachineId();
+  }
+  getMachineName() {
+    return config.getMachineName();
+  }
+};
+var authService = new AuthServiceImpl();
+
+// src/services/api.ts
+var require2 = createRequire(import.meta.url);
+var packageJson = require2("../../package.json");
+var AGENT_VERSION = packageJson.version;
+var ApiServiceImpl = class {
+  sessionId = null;
+  async getHeaders() {
+    const token = await authService.getToken();
+    if (!token) {
+      throw new Error('No authentication token found. Please run "stint login" first.');
+    }
+    return {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json"
+    };
+  }
+  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
+        }
+      });
+      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;
+    }
+  }
+  /**
+   * Retry wrapper with exponential backoff
+   */
+  async withRetry(operation, operationName, maxRetries = 3) {
+    let lastError;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        return await operation();
+      } catch (error) {
+        lastError = error;
+        if (lastError.message.includes("401") || lastError.message.includes("403")) {
+          throw lastError;
+        }
+        if (attempt < maxRetries) {
+          const delay = Math.min(1e3 * Math.pow(2, attempt - 1), 5e3);
+          logger.warn("api", `${operationName} failed, retrying in ${delay}ms (attempt ${attempt}/${maxRetries})`);
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        } else {
+          logger.error("api", `${operationName} failed after ${maxRetries} attempts`);
+        }
+      }
+    }
+    throw lastError;
+  }
+  async connect() {
+    logger.info("api", "Connecting agent session...");
+    const os4 = `${process.platform}-${process.arch}`;
+    return this.withRetry(async () => {
+      const response = await this.request("/api/agent/connect", {
+        method: "POST",
+        body: JSON.stringify({
+          machine_id: authService.getMachineId(),
+          machine_name: authService.getMachineName(),
+          os: os4,
+          agent_version: AGENT_VERSION
+        })
+      });
+      const session = response.data;
+      this.sessionId = session.id;
+      logger.success("api", `Agent session connected: ${session.id}`);
+      return session;
+    }, "Connect");
+  }
+  async disconnect() {
+    if (!this.sessionId) {
+      return;
+    }
+    logger.info("api", "Disconnecting agent session...");
+    await this.request("/api/agent/disconnect", {
+      method: "POST",
+      body: JSON.stringify({
+        session_id: this.sessionId
+      })
+    });
+    this.sessionId = null;
+    logger.success("api", "Agent session disconnected");
+  }
+  async heartbeat() {
+    if (!this.sessionId) {
+      throw new Error("No active session");
+    }
+    await this.withRetry(async () => {
+      await this.request("/api/agent/heartbeat", {
+        method: "POST",
+        body: JSON.stringify({
+          session_id: this.sessionId
+        })
+      });
+      logger.debug("api", "Heartbeat sent");
+    }, "Heartbeat");
+  }
+  async getPendingCommits(projectId) {
+    logger.info("api", `Fetching pending commits for project ${projectId}`);
+    const commits = await this.request(
+      `/api/agent/projects/${projectId}/pending-commits`
+    );
+    logger.info("api", `Found ${commits.length} pending commits`);
+    return commits;
+  }
+  async markCommitExecuted(commitId, sha) {
+    logger.info("api", `Marking commit ${commitId} as executed (SHA: ${sha})`);
+    return this.withRetry(async () => {
+      const commit = await this.request(
+        `/api/agent/commits/${commitId}/executed`,
+        {
+          method: "POST",
+          body: JSON.stringify({ sha })
+        }
+      );
+      logger.success("api", `Commit ${commitId} marked as executed`);
+      return commit;
+    }, "Mark commit executed");
+  }
+  async markCommitFailed(commitId, error) {
+    logger.error("api", `Marking commit ${commitId} as failed: ${error}`);
+    await this.withRetry(async () => {
+      await this.request(`/api/agent/commits/${commitId}/failed`, {
+        method: "POST",
+        body: JSON.stringify({ error })
+      });
+    }, "Mark commit failed");
+  }
+  async syncProject(projectId, data) {
+    logger.info("api", `Syncing project ${projectId}`);
+    await this.withRetry(async () => {
+      await this.request(`/api/agent/projects/${projectId}/sync`, {
+        method: "POST",
+        body: JSON.stringify(data)
+      });
+      logger.success("api", `Project ${projectId} synced`);
+    }, "Sync project");
+  }
+  async getLinkedProjects() {
+    logger.info("api", "Fetching linked projects");
+    const projects = await this.request("/api/agent/projects");
+    logger.info("api", `Found ${projects.length} linked projects`);
+    return projects;
+  }
+  async getCurrentUser() {
+    logger.info("api", "Fetching current user");
+    const user = await this.request("/api/user");
+    logger.info("api", `Fetched user: ${user.email}`);
+    return user;
+  }
+};
+var apiService = new ApiServiceImpl();
+
+export {
+  config,
+  logger,
+  apiService,
+  authService
+};