retestkit 1.13.0 → 1.15.0

package/README.md

@@ -75,27 +75,217 @@ npm run test:e2e
 
 E2E tests have extended timeouts (5 minutes per test) and run serially to avoid resource contention. They create isolated temporary workspaces that are cleaned up after each test.
 
+## Quick Start
+
+RetestKit is designed for **zero-configuration installation**. Just add the server to your MCP client and run `/init` to configure.
+
+### Adding to MCP Clients
+
+**VS Code / GitHub Copilot** (`.vscode/mcp.json`):
+```json
+{
+  "servers": {
+    "retestkit": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["retestkit"]
+    }
+  }
+}
+```
+
+**Claude Desktop** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "retestkit": {
+      "command": "npx",
+      "args": ["retestkit"]
+    }
+  }
+}
+```
+
+**Cursor / Cline** (settings):
+```json
+{
+  "mcpServers": {
+    "retestkit": {
+      "command": "npx",
+      "args": ["retestkit"]
+    }
+  }
+}
+```
+
+> **Note:** No `env` or `inputs` sections needed. All configuration happens via the `/init` prompt after the server starts.
+
+### First-Time Setup
+
+After adding the server to your MCP client:
+
+1. **Run `/init`** - The init prompt guides you through configuration
+2. **Provide target URL** - The URL of the web application to test
+3. **Configuration saved** - Settings are stored in `.mcp/retestkit.json`
+
+The `/init` prompt handles:
+- Creating the config file (`.mcp/retestkit.json`)
+- Setting up shortcuts (e.g., `/retest` command)
+- Guiding you to start testing with `/cover`
+
 ## Configuration
 
-Configuration is done via environment variables:
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `TRANSPORT` | `stdio` | Transport type: `stdio` or `http` |
-| `PORT` | `3000` | HTTP port (when `TRANSPORT=http`) |
-| `LOG_LEVEL` | `info` | Log level: `debug`, `info`, `warn`, `error` |
-| `RETEST_WORKSPACE_DIR` | `./retest` | Directory for analysis workspaces |
-| `PLAYWRIGHT_MCP_COMMAND` | `npx` | Command to spawn Playwright MCP |
-| `PLAYWRIGHT_MCP_ARGS` | `@playwright/mcp@latest` | Comma-separated args for Playwright MCP |
-| `CHECKPOINT_INTERVAL` | `5` | Steps between crawl checkpoints |
-| `SCREENSHOT_FORMAT` | `png` | Screenshot format: `png` or `jpeg` |
-| `SCREENSHOT_QUALITY` | `80` | JPEG quality (1-100) |
-| `DEFAULT_MAX_STEPS` | `50` | Default max crawl steps |
-| `DEFAULT_MAX_MINUTES` | `30` | Default max crawl duration |
-| `DEFAULT_MAX_PAGES` | `20` | Default max pages to crawl |
+RetestKit uses `.mcp/retestkit.json` for all configuration. This file is created automatically when you run `/init`.
+
+**Example `.mcp/retestkit.json`:**
+```json
+{
+  "version": 1,
+  "targetUrl": "https://myapp.com",
+  "specsPath": "./specs",
+  "allowedDomains": ["myapp.com", "*.myapp.com"],
+  "transport": "stdio",
+  "port": 3000,
+  "workspaceDir": "./retest",
+  "limits": {
+    "maxSteps": 50,
+    "maxMinutes": 30,
+    "maxPages": 20
+  },
+  "logging": {
+    "level": "info"
+  },
+  "playwright": {
+    "command": "npx",
+    "args": ["@playwright/mcp@latest"]
+  },
+  "checkpointInterval": 5,
+  "screenshotFormat": "png",
+  "screenshotQuality": 80
+}
+```
+
+**Config file discovery order:**
+1. CLI flag: `--config /path/to/config.json`
+2. Environment: `RETESTKIT_CONFIG=/path/to/config.json`
+3. Workspace: `./.mcp/retestkit.json`
+4. User-level: `~/.config/retestkit/config.json`
+5. Built-in defaults
+
+> **Note:** Environment variables are **not supported** for configuration values. Only `RETESTKIT_CONFIG` is recognized (to specify the config file path for CI/CD pipelines).
+
+## Authentication
+
+RetestKit supports OAuth 2.0 Device Code Flow authentication for accessing protected features. Authentication is handled via the `auth` MCP tool.
+
+### Quick Start
+
+```
+# Check authentication status
+auth({ action: "status" })
+
+# Log in (opens browser for authentication)
+auth({ action: "login" })
+
+# Log out
+auth({ action: "logout" })
+```
+
+### How It Works
+
+The device code flow is designed for STDIO-based tools that can't receive HTTP callbacks:
+
+1. Call `auth({ action: "login" })` to start the flow
+2. A browser window opens (or a URL is displayed) for authentication
+3. Complete login in your browser
+4. The tool polls for completion and stores tokens securely
+
+### Tool Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `action` | string | `"login"` | Action: `login`, `status`, `logout`, or `continue` |
+| `wait` | boolean | `true` | Wait for login completion (login/continue only) |
+| `waitSeconds` | number | `25` | Max seconds to wait before returning pending status |
+
+### Actions
+
+- **`login`** - Start device code flow. If already logged in, returns current status.
+- **`status`** - Check current authentication status without starting a new flow.
+- **`logout`** - Clear stored tokens and end the session.
+- **`continue`** - Resume polling for a pending login (useful for short MCP timeouts).
+
+### Example Responses
+
+**Pending login:**
+```json
+{
+  "status": "pending",
+  "message": "Open the URL below to complete login...",
+  "deviceFlow": {
+    "verificationUri": "https://auth.retestkit.dev/device",
+    "verificationUriComplete": "https://auth.retestkit.dev/device?code=ABCD-1234",
+    "userCode": "ABCD-1234",
+    "expiresAt": "2025-01-15T10:15:00Z"
+  }
+}
+```
+
+**Logged in:**
+```json
+{
+  "status": "logged_in",
+  "message": "Logged in as user@example.com",
+  "user": {
+    "email": "user@example.com",
+    "name": "User Name"
+  }
+}
+```
+
+### Token Storage
+
+Tokens are stored securely using:
+1. **OS Keychain** (preferred) - macOS Keychain, Windows Credential Manager, Linux libsecret
+2. **Encrypted file** (fallback) - `~/.config/retestkit/tokens.enc` with 0600 permissions
+
+### Auth Configuration
+
+Optional auth configuration in `.mcp/retestkit.json`:
+
+```json
+{
+  "auth": {
+    "authentikBaseUrl": "https://auth.retestkit.dev",
+    "clientId": "retestkit-mcp",
+    "scopes": "openid profile email offline_access"
+  }
+}
+```
+
+> **Note:** Default values work out of the box. Only customize if using a different authentication provider.
 
 ## Available Tools
 
+### `auth`
+
+Manage authentication for protected RetestKit features.
+
+**Input:**
+```json
+{
+  "action": "login",
+  "wait": true,
+  "waitSeconds": 25
+}
+```
+
+**Actions:** `login` (default), `status`, `logout`, `continue`
+
+**Output:** Status, user info (when logged in), device flow info (when pending)
+
+See [Authentication](#authentication) section for details.
+
 ### `retest_init`
 
 Initialize a new web testing analysis workspace.

package/dist/auth/browser.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Best-effort browser opening utility.
+ *
+ * Attempts to open a URL in the user's default browser.
+ * Fails gracefully if no browser is available.
+ */
+/**
+ * Attempt to open a URL in the user's default browser.
+ *
+ * @param url URL to open
+ * @returns true if browser was opened, false otherwise
+ */
+export declare function openBrowser(url: string): Promise<boolean>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/auth/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/auth/browser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkBH;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CA8B/D"}

package/dist/auth/browser.js

@@ -0,0 +1,67 @@
+/**
+ * Best-effort browser opening utility.
+ *
+ * Attempts to open a URL in the user's default browser.
+ * Fails gracefully if no browser is available.
+ */
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+const execAsync = promisify(exec);
+/**
+ * Platform-specific browser open commands.
+ */
+const OPEN_COMMANDS = {
+    darwin: ["open"],
+    win32: ["cmd", "/c", "start", '""'],
+    linux: ["xdg-open"],
+    freebsd: ["xdg-open"],
+    openbsd: ["xdg-open"],
+};
+/**
+ * Attempt to open a URL in the user's default browser.
+ *
+ * @param url URL to open
+ * @returns true if browser was opened, false otherwise
+ */
+export async function openBrowser(url) {
+    const platform = process.platform;
+    const cmdParts = OPEN_COMMANDS[platform];
+    if (!cmdParts) {
+        // Unsupported platform
+        return false;
+    }
+    try {
+        // Validate URL to prevent command injection
+        const parsedUrl = new URL(url);
+        if (!["http:", "https:"].includes(parsedUrl.protocol)) {
+            return false;
+        }
+        // Escape URL for shell (different escaping per platform)
+        const escapedUrl = escapeUrlForPlatform(url, platform);
+        const command = [...cmdParts, escapedUrl].join(" ");
+        await execAsync(command, {
+            timeout: 5000, // 5 second timeout
+            windowsHide: true, // Don't show command window on Windows
+        });
+        return true;
+    }
+    catch {
+        // Browser open failed - this is non-fatal
+        return false;
+    }
+}
+/**
+ * Escape URL for shell command based on platform.
+ */
+function escapeUrlForPlatform(url, platform) {
+    if (platform === "win32") {
+        // Windows: wrap in quotes, escape special characters
+        // The URL is already reasonably safe since we validated it
+        return `"${url.replace(/"/g, "")}"`;
+    }
+    else {
+        // Unix-like: wrap in single quotes, escape single quotes
+        return `'${url.replace(/'/g, "'\\''")}'`;
+    }
+}
+//# sourceMappingURL=browser.js.map

package/dist/auth/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/auth/browser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;AAElC;;GAEG;AACH,MAAM,aAAa,GAA6B;IAC9C,MAAM,EAAE,CAAC,MAAM,CAAC;IAChB,KAAK,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC;IACnC,KAAK,EAAE,CAAC,UAAU,CAAC;IACnB,OAAO,EAAE,CAAC,UAAU,CAAC;IACrB,OAAO,EAAE,CAAC,UAAU,CAAC;CACtB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAW;IAC3C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAClC,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IAEzC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,uBAAuB;QACvB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,CAAC;QACH,4CAA4C;QAC5C,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;YACtD,OAAO,KAAK,CAAC;QACf,CAAC;QAED,yDAAyD;QACzD,MAAM,UAAU,GAAG,oBAAoB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QACvD,MAAM,OAAO,GAAG,CAAC,GAAG,QAAQ,EAAE,UAAU,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAEpD,MAAM,SAAS,CAAC,OAAO,EAAE;YACvB,OAAO,EAAE,IAAI,EAAE,mBAAmB;YAClC,WAAW,EAAE,IAAI,EAAE,uCAAuC;SAC3D,CAAC,CAAC;QAEH,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,0CAA0C;QAC1C,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAS,oBAAoB,CAAC,GAAW,EAAE,QAAgB;IACzD,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACzB,qDAAqD;QACrD,2DAA2D;QAC3D,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC;IACtC,CAAC;SAAM,CAAC;QACN,yDAAyD;QACzD,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC;IAC3C,CAAC;AACH,CAAC"}

package/dist/auth/device-flow.d.ts

@@ -0,0 +1,80 @@
+/**
+ * OAuth 2.0 Device Authorization Grant flow manager.
+ *
+ * Implements RFC 8628 for STDIO-compatible authentication.
+ */
+import type { AuthConfig, PendingDeviceFlowSession } from "./types.js";
+import { TokenManager } from "./token-manager.js";
+/**
+ * Result of a device flow start operation.
+ */
+export interface DeviceFlowStartResult {
+    /** User code for display */
+    userCode: string;
+    /** Verification URL for manual entry */
+    verificationUri: string;
+    /** Complete verification URL (with embedded code) */
+    verificationUriComplete?: string;
+    /** When the code expires */
+    expiresAt: string;
+    /** Whether browser was opened */
+    browserOpened: boolean;
+}
+/**
+ * Result of polling for token completion.
+ */
+export interface DeviceFlowPollResult {
+    /** Whether polling completed successfully */
+    completed: boolean;
+    /** Whether flow is still pending */
+    pending: boolean;
+    /** Error if flow failed */
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Device Flow Manager for handling OAuth device code flow.
+ */
+export declare class DeviceFlowManager {
+    private config;
+    private tokenManager;
+    private pendingSession;
+    constructor(tokenManager: TokenManager, config?: Partial<AuthConfig>);
+    /**
+     * Start a new device authorization flow.
+     *
+     * @param openBrowserWindow Whether to attempt opening the browser
+     * @returns Start result with verification URLs and codes
+     */
+    startFlow(openBrowserWindow?: boolean): Promise<DeviceFlowStartResult>;
+    /**
+     * Poll for token completion.
+     *
+     * @param maxWaitSeconds Maximum time to wait
+     * @returns Poll result
+     */
+    pollToken(maxWaitSeconds?: number): Promise<DeviceFlowPollResult>;
+    /**
+     * Get the current pending session state.
+     */
+    getPending(): PendingDeviceFlowSession | null;
+    /**
+     * Clear the pending session.
+     */
+    clearPending(): void;
+    /**
+     * Check if there's an active pending session.
+     */
+    hasPending(): boolean;
+    /**
+     * Sleep helper for polling.
+     */
+    private sleep;
+}
+/**
+ * Create a device flow manager instance.
+ */
+export declare function createDeviceFlowManager(tokenManager: TokenManager, config?: Partial<AuthConfig>): DeviceFlowManager;
+//# sourceMappingURL=device-flow.d.ts.map

package/dist/auth/device-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-flow.d.ts","sourceRoot":"","sources":["../../src/auth/device-flow.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,UAAU,EAGV,wBAAwB,EAGzB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AASlD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IAEjB,wCAAwC;IACxC,eAAe,EAAE,MAAM,CAAC;IAExB,qDAAqD;IACrD,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAEjC,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAElB,iCAAiC;IACjC,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,6CAA6C;IAC7C,SAAS,EAAE,OAAO,CAAC;IAEnB,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IAEjB,2BAA2B;IAC3B,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,cAAc,CAAyC;gBAEnD,YAAY,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC;IAKpE;;;;;OAKG;IACG,SAAS,CAAC,iBAAiB,UAAO,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAuEzE;;;;;OAKG;IACG,SAAS,CAAC,cAAc,SAAK,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAyInE;;OAEG;IACH,UAAU,IAAI,wBAAwB,GAAG,IAAI;IAc7C;;OAEG;IACH,YAAY,IAAI,IAAI;IAIpB;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACH,OAAO,CAAC,KAAK;CAGd;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,YAAY,EAC1B,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAC3B,iBAAiB,CAEnB"}

package/dist/auth/device-flow.js

@@ -0,0 +1,243 @@
+/**
+ * OAuth 2.0 Device Authorization Grant flow manager.
+ *
+ * Implements RFC 8628 for STDIO-compatible authentication.
+ */
+import { AuthError, DEFAULT_AUTH_CONFIG } from "./types.js";
+import { openBrowser } from "./browser.js";
+/** Default poll interval in seconds */
+const DEFAULT_POLL_INTERVAL = 5;
+/** Slow down increment when server requests it */
+const SLOW_DOWN_INCREMENT = 5;
+/**
+ * Device Flow Manager for handling OAuth device code flow.
+ */
+export class DeviceFlowManager {
+    config;
+    tokenManager;
+    pendingSession = null;
+    constructor(tokenManager, config) {
+        this.config = { ...DEFAULT_AUTH_CONFIG, ...config };
+        this.tokenManager = tokenManager;
+    }
+    /**
+     * Start a new device authorization flow.
+     *
+     * @param openBrowserWindow Whether to attempt opening the browser
+     * @returns Start result with verification URLs and codes
+     */
+    async startFlow(openBrowserWindow = true) {
+        const deviceUrl = `${this.config.authentikBaseUrl}/application/o/device/`;
+        const params = new URLSearchParams({
+            client_id: this.config.clientId,
+            scope: this.config.scopes,
+        });
+        try {
+            const response = await fetch(deviceUrl, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                },
+                body: params.toString(),
+            });
+            if (!response.ok) {
+                const errorData = (await response.json().catch(() => ({})));
+                throw new AuthError(errorData.error || "device_auth_failed", errorData.error_description || "Failed to start device authorization", true);
+            }
+            const data = (await response.json());
+            // Calculate expiry
+            const expiresAt = new Date(Date.now() + data.expires_in * 1000).toISOString();
+            // Store pending session
+            this.pendingSession = {
+                deviceCode: data.device_code,
+                userCode: data.user_code,
+                verificationUri: data.verification_uri,
+                verificationUriComplete: data.verification_uri_complete,
+                expiresAt,
+                pollInterval: data.interval || DEFAULT_POLL_INTERVAL,
+            };
+            // Attempt to open browser
+            let browserOpened = false;
+            if (openBrowserWindow) {
+                const urlToOpen = data.verification_uri_complete || data.verification_uri;
+                browserOpened = await openBrowser(urlToOpen);
+            }
+            return {
+                userCode: data.user_code,
+                verificationUri: data.verification_uri,
+                verificationUriComplete: data.verification_uri_complete,
+                expiresAt,
+                browserOpened,
+            };
+        }
+        catch (error) {
+            if (error instanceof AuthError) {
+                throw error;
+            }
+            throw new AuthError("network_error", `Unable to reach auth server: ${error instanceof Error ? error.message : "Unknown error"}`, true);
+        }
+    }
+    /**
+     * Poll for token completion.
+     *
+     * @param maxWaitSeconds Maximum time to wait
+     * @returns Poll result
+     */
+    async pollToken(maxWaitSeconds = 25) {
+        if (!this.pendingSession) {
+            throw new AuthError("no_pending_session", "No pending device flow session. Start a new login flow.", false);
+        }
+        // Check if session expired
+        if (new Date(this.pendingSession.expiresAt) < new Date()) {
+            this.pendingSession = null;
+            return {
+                completed: false,
+                pending: false,
+                error: {
+                    code: "expired_token",
+                    message: "Login session expired. Please try again.",
+                },
+            };
+        }
+        const tokenUrl = `${this.config.authentikBaseUrl}/application/o/token/`;
+        const startTime = Date.now();
+        const maxWaitMs = maxWaitSeconds * 1000;
+        while (Date.now() - startTime < maxWaitMs) {
+            // Respect poll interval
+            const now = Date.now();
+            if (this.pendingSession.lastPollAt) {
+                const lastPoll = new Date(this.pendingSession.lastPollAt).getTime();
+                const timeSinceLastPoll = now - lastPoll;
+                const waitTime = this.pendingSession.pollInterval * 1000 - timeSinceLastPoll;
+                if (waitTime > 0) {
+                    await this.sleep(Math.min(waitTime, maxWaitMs - (now - startTime)));
+                    if (Date.now() - startTime >= maxWaitMs) {
+                        break;
+                    }
+                }
+            }
+            this.pendingSession.lastPollAt = new Date().toISOString();
+            const params = new URLSearchParams({
+                grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                client_id: this.config.clientId,
+                device_code: this.pendingSession.deviceCode,
+            });
+            try {
+                const response = await fetch(tokenUrl, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/x-www-form-urlencoded",
+                    },
+                    body: params.toString(),
+                });
+                if (response.ok) {
+                    // Success! Store tokens and clear pending session
+                    const tokenResponse = (await response.json());
+                    await this.tokenManager.storeFromResponse(tokenResponse);
+                    this.pendingSession = null;
+                    return {
+                        completed: true,
+                        pending: false,
+                    };
+                }
+                const errorData = (await response.json());
+                const errorCode = errorData.error;
+                switch (errorCode) {
+                    case "authorization_pending":
+                        // Still waiting - continue polling
+                        break;
+                    case "slow_down":
+                        // Increase poll interval
+                        this.pendingSession.pollInterval += SLOW_DOWN_INCREMENT;
+                        break;
+                    case "expired_token":
+                        this.pendingSession = null;
+                        return {
+                            completed: false,
+                            pending: false,
+                            error: {
+                                code: "expired_token",
+                                message: "Login session expired. Please try again.",
+                            },
+                        };
+                    case "access_denied":
+                        this.pendingSession = null;
+                        return {
+                            completed: false,
+                            pending: false,
+                            error: {
+                                code: "access_denied",
+                                message: "Login was denied. Please try again.",
+                            },
+                        };
+                    default:
+                        // Unknown error - clear session and report
+                        this.pendingSession = null;
+                        return {
+                            completed: false,
+                            pending: false,
+                            error: {
+                                code: errorCode || "unknown",
+                                message: errorData.error_description || "Login failed.",
+                            },
+                        };
+                }
+            }
+            catch (error) {
+                // Network error during poll - don't clear session, allow retry
+                return {
+                    completed: false,
+                    pending: true,
+                    error: {
+                        code: "network_error",
+                        message: `Unable to reach auth server: ${error instanceof Error ? error.message : "Unknown error"}`,
+                    },
+                };
+            }
+        }
+        // Timeout - session still pending
+        return {
+            completed: false,
+            pending: true,
+        };
+    }
+    /**
+     * Get the current pending session state.
+     */
+    getPending() {
+        if (!this.pendingSession) {
+            return null;
+        }
+        // Check if expired
+        if (new Date(this.pendingSession.expiresAt) < new Date()) {
+            this.pendingSession = null;
+            return null;
+        }
+        return { ...this.pendingSession };
+    }
+    /**
+     * Clear the pending session.
+     */
+    clearPending() {
+        this.pendingSession = null;
+    }
+    /**
+     * Check if there's an active pending session.
+     */
+    hasPending() {
+        return this.getPending() !== null;
+    }
+    /**
+     * Sleep helper for polling.
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+/**
+ * Create a device flow manager instance.
+ */
+export function createDeviceFlowManager(tokenManager, config) {
+    return new DeviceFlowManager(tokenManager, config);
+}
+//# sourceMappingURL=device-flow.js.map

package/dist/auth/device-flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-flow.js","sourceRoot":"","sources":["../../src/auth/device-flow.ts"],"names":[],"mappings":"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"}