opencode-qwen-cli-auth 2.2.8 → 2.3.0

package/dist/lib/config.js

@@ -1,30 +1,46 @@
+/**
+ * @fileoverview Configuration utilities for Qwen OAuth Plugin
+ * Manages paths for configuration, tokens, and cache directories
+ * @license MIT
+ */
+
 import { homedir } from "os";
 import { join } from "path";
 import { readFileSync, existsSync } from "fs";
+
 /**
  * Get plugin configuration directory
+ * @returns {string} Path to ~/.opencode/qwen/
  */
 export function getConfigDir() {
     return join(homedir(), ".opencode", "qwen");
 }
+
 /**
  * Get Qwen CLI credential directory (~/.qwen)
+ * This directory is shared with the official qwen-code CLI for token storage
+ * @returns {string} Path to ~/.qwen/
  */
 export function getQwenDir() {
     return join(homedir(), ".qwen");
 }
+
 /**
  * Get plugin configuration file path
+ * @returns {string} Path to ~/.opencode/qwen/auth-config.json
  */
 export function getConfigPath() {
     return join(getConfigDir(), "auth-config.json");
 }
+
 /**
  * Load plugin configuration from ~/.opencode/qwen/auth-config.json
  * Returns default config if file doesn't exist
+ * @returns {{ qwenMode: boolean }} Configuration object with qwenMode flag
  */
 export function loadPluginConfig() {
     const configPath = getConfigPath();
+    // Return default config if config file doesn't exist
     if (!existsSync(configPath)) {
         return { qwenMode: true }; // Default: QWEN_MODE enabled
     }
@@ -33,15 +49,20 @@ export function loadPluginConfig() {
         return JSON.parse(content);
     }
     catch (error) {
+        // Log warning and return default config on parse error
         console.warn(`[qwen-oauth-plugin] Failed to load config from ${configPath}:`, error);
         return { qwenMode: true };
     }
 }
+
 /**
  * Get QWEN_MODE setting
  * Priority: QWEN_MODE env var > config file > default (true)
+ * @param {{ qwenMode?: boolean|string|null }} config - Configuration object from file
+ * @returns {boolean} True if QWEN_MODE is enabled, false otherwise
  */
 export function getQwenMode(config) {
+    // Environment variable takes highest priority
     const envValue = process.env.QWEN_MODE;
     if (envValue !== undefined) {
         return envValue === "1" || envValue.toLowerCase() === "true";
@@ -49,31 +70,44 @@ export function getQwenMode(config) {
     // Ensure boolean type, avoid string "false" being truthy
     const val = config.qwenMode;
     if (val === undefined || val === null) return true; // default: enabled
+    // Handle string values from config file
     if (typeof val === "string") {
         return val === "1" || val.toLowerCase() === "true";
     }
+    // Convert to boolean for actual boolean values
     return !!val;
 }
+
 /**
  * Get token storage path
+ * Token file contains OAuth credentials: access_token, refresh_token, expiry_date, resource_url
+ * @returns {string} Path to ~/.qwen/oauth_creds.json
  */
 export function getTokenPath() {
     return join(getQwenDir(), "oauth_creds.json");
 }
+
 /**
  * Get token lock path for multi-process refresh coordination
+ * Prevents concurrent token refresh operations across multiple processes
+ * @returns {string} Path to ~/.qwen/oauth_creds.lock
  */
 export function getTokenLockPath() {
     return join(getQwenDir(), "oauth_creds.lock");
 }
+
 /**
  * Get legacy token storage path used by old plugin versions
+ * Used for backward compatibility and token migration
+ * @returns {string} Path to ~/.opencode/qwen/oauth_token.json
  */
 export function getLegacyTokenPath() {
     return join(getConfigDir(), "oauth_token.json");
 }
+
 /**
  * Get cache directory for prompts
+ * @returns {string} Path to ~/.opencode/cache/
  */
 export function getCacheDir() {
     return join(homedir(), ".opencode", "cache");

package/dist/lib/constants.d.ts

@@ -8,15 +8,15 @@ export declare const PROVIDER_ID = "qwen-code";
 /** Dummy API key (actual auth via OAuth) */
 export declare const DUMMY_API_KEY = "qwen-oauth";
 /**
- * Default Qwen Portal API base URL (fallback if resource_url is missing)
+ * Default Qwen DashScope base URL (fallback if resource_url is missing)
  * Note: This plugin is for OAuth authentication only. For API key authentication,
  * use OpenCode's built-in DashScope support.
  *
- * IMPORTANT: Portal API uses /v1 path (not /api/v1)
+ * IMPORTANT: OAuth endpoints use /api/v1, DashScope OpenAI-compatible uses /compatible-mode/v1
  * - OAuth endpoints: /api/v1/oauth2/ (for authentication)
  * - Chat API: /v1/ (for completions)
  */
-export declare const DEFAULT_QWEN_BASE_URL = "https://portal.qwen.ai/v1";
+export declare const DEFAULT_QWEN_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1";
 /** Qwen OAuth endpoints and configuration */
 export declare const QWEN_OAUTH: {
     readonly DEVICE_CODE_URL: "https://chat.qwen.ai/api/v1/oauth2/device/code";
@@ -40,8 +40,8 @@ export declare const HTTP_STATUS: {
     readonly TOO_MANY_REQUESTS: 429;
 };
 /**
- * Portal API headers
- * Note: Portal API (OAuth) requires special header to indicate OAuth authentication
+ * DashScope headers
+ * Note: OAuth requires X-DashScope-AuthType to indicate qwen-oauth authentication
  */
 export declare const PORTAL_HEADERS: {
     readonly AUTH_TYPE: "X-DashScope-AuthType";

package/dist/lib/constants.js

@@ -1,37 +1,69 @@
 /**
- * Constants for Qwen OAuth Plugin
+ * @fileoverview Constants for Qwen OAuth Plugin
+ * Centralized configuration for OAuth endpoints, headers, error codes, and other constants
+ * @license MIT
  */
-/** Plugin identifier */
+
+/** Plugin identifier for logging and debugging */
 export const PLUGIN_NAME = "qwen-oauth-plugin";
-/** Provider ID for opencode configuration (used in model references like qwen-code/coder-model) */
+
+/**
+ * Provider ID for opencode configuration
+ * Used in model references like qwen-code/coder-model
+ */
 export const PROVIDER_ID = "qwen-code";
-/** Dummy API key (actual auth via OAuth) */
+
+/**
+ * Dummy API key placeholder
+ * Actual authentication is handled via OAuth flow, not API key
+ */
 export const DUMMY_API_KEY = "qwen-oauth";
+
 /**
- * Default Qwen Portal API base URL (fallback if resource_url is missing)
+ * Default Qwen DashScope base URL (fallback if resource_url is missing)
  * Note: This plugin is for OAuth authentication only. For API key authentication,
  * use OpenCode's built-in DashScope support.
  *
- * IMPORTANT: Portal API uses /v1 path (not /api/v1)
+ * IMPORTANT: OAuth endpoints use /api/v1, DashScope OpenAI-compatible uses /compatible-mode/v1
  * - OAuth endpoints: /api/v1/oauth2/ (for authentication)
  * - Chat API: /v1/ (for completions)
+ *
+ * @constant {string}
+ */
+// NOTE:
+// qwen-code (official CLI) defaults to DashScope OpenAI-compatible endpoint when
+// `resource_url` is missing. This is required for the free OAuth flow to behave
+// the same as the CLI.
+export const DEFAULT_QWEN_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1";
+
+/**
+ * Qwen OAuth endpoints and configuration
+ * Source: Qwen Code CLI (https://github.com/QwenLM/qwen-code)
+ * @namespace
  */
-export const DEFAULT_QWEN_BASE_URL = "https://portal.qwen.ai/v1";
-/** Qwen OAuth endpoints and configuration */
 export const QWEN_OAUTH = {
+    /** OAuth 2.0 Device Code endpoint */
     DEVICE_CODE_URL: "https://chat.qwen.ai/api/v1/oauth2/device/code",
+    /** OAuth 2.0 Token endpoint */
     TOKEN_URL: "https://chat.qwen.ai/api/v1/oauth2/token",
     /**
      * Qwen OAuth Client ID
-     * Source: Qwen Code CLI (https://github.com/QwenLM/qwen-code)
      * This is a public client ID used for OAuth Device Authorization Grant flow (RFC 8628)
+     * @constant {string}
      */
     CLIENT_ID: "f0304373b74a44d2b584a3fb70ca9e56",
+    /** OAuth scopes requested: openid, profile, email, and model completion access */
     SCOPE: "openid profile email model.completion",
+    /** OAuth 2.0 Device Code grant type (RFC 8628) */
     GRANT_TYPE_DEVICE: "urn:ietf:params:oauth:grant-type:device_code",
+    /** OAuth 2.0 Refresh Token grant type */
     GRANT_TYPE_REFRESH: "refresh_token",
 };
-/** HTTP Status Codes */
+
+/**
+ * HTTP Status Codes for error handling
+ * @namespace
+ */
 export const HTTP_STATUS = {
     OK: 200,
     BAD_REQUEST: 400,
@@ -39,21 +71,37 @@ export const HTTP_STATUS = {
     FORBIDDEN: 403,
     TOO_MANY_REQUESTS: 429,
 };
+
 /**
- * Portal API headers
- * Note: Portal API (OAuth) requires special header to indicate OAuth authentication
+ * DashScope headers for OAuth authentication
+ * Note: OAuth requires X-DashScope-AuthType to indicate qwen-oauth authentication
+ * @namespace
  */
 export const PORTAL_HEADERS = {
+    /** Header name for auth type specification */
     AUTH_TYPE: "X-DashScope-AuthType",
+    /** Header value for qwen-oauth authentication */
     AUTH_TYPE_VALUE: "qwen-oauth",
 };
-/** Device flow polling configuration */
+
+/**
+ * Device flow polling configuration
+ * Controls backoff strategy for OAuth token polling
+ * @namespace
+ */
 export const DEVICE_FLOW = {
+    /** Initial polling interval in milliseconds */
     INITIAL_POLL_INTERVAL: 2000, // 2 seconds
+    /** Maximum polling interval in milliseconds */
     MAX_POLL_INTERVAL: 10000, // 10 seconds
+    /** Backoff multiplier for exponential backoff */
     BACKOFF_MULTIPLIER: 1.5,
 };
-/** Error messages */
+
+/**
+ * Error messages for user-facing errors
+ * @namespace
+ */
 export const ERROR_MESSAGES = {
     TOKEN_REFRESH_FAILED: "Failed to refresh token, authentication required",
     DEVICE_AUTH_TIMEOUT: "Device authorization timed out",
@@ -61,14 +109,27 @@ export const ERROR_MESSAGES = {
     REQUEST_PARSE_ERROR: "Error parsing request",
     NO_RESOURCE_URL: "No resource_url in token response, using default",
 };
-/** OAuth error codes */
+
+/**
+ * OAuth error codes from RFC 8628 Device Flow
+ * @namespace
+ */
 export const OAUTH_ERRORS = {
+    /** User has not yet authorized the device code */
     AUTHORIZATION_PENDING: "authorization_pending",
+    /** Server requests slower polling (slow_down error) */
     SLOW_DOWN: "slow_down",
+    /** User denied the authorization request */
     ACCESS_DENIED: "access_denied",
+    /** Device code has expired */
     EXPIRED_TOKEN: "expired_token",
 };
-/** Log stages for request logging */
+
+/**
+ * Log stages for request logging
+ * Used for debugging and tracing request lifecycle
+ * @namespace
+ */
 export const LOG_STAGES = {
     BEFORE_TRANSFORM: "before-transform",
     AFTER_TRANSFORM: "after-transform",
@@ -77,29 +138,53 @@ export const LOG_STAGES = {
     DEVICE_CODE_REQUEST: "device-code-request",
     TOKEN_POLL: "token-poll",
 };
-/** Platform-specific browser opener commands */
+
+/**
+ * Platform-specific browser opener commands
+ * Used for opening OAuth verification URL in default browser
+ * @namespace
+ */
 export const PLATFORM_OPENERS = {
     darwin: "open",
     win32: "start",
     linux: "xdg-open",
 };
-/** OAuth authorization labels */
+
+/**
+ * OAuth authorization labels for UI display
+ * @namespace
+ */
 export const AUTH_LABELS = {
+    /** Label shown in OpenCode auth provider selection */
     OAUTH: "Qwen Code (qwen.ai OAuth)",
+    /** Instructions shown to user during OAuth flow */
     INSTRUCTIONS: "Visit the URL shown in your browser to complete authentication.",
 };
-/** OAuth verification URI parameters */
+
+/**
+ * OAuth verification URI parameters
+ * Used to construct complete verification URL with client identification
+ * @namespace
+ */
 export const VERIFICATION_URI = {
     /** Query parameter key for client identification */
     CLIENT_PARAM_KEY: "client=",
     /** Full query parameter for Qwen Code client */
     CLIENT_PARAM_VALUE: "client=qwen-code",
 };
-/** Token refresh buffer (refresh 30 seconds before expiry) */
+
+/**
+ * Token refresh buffer in milliseconds
+ * Tokens are refreshed 30 seconds before expiry to avoid race conditions
+ * @constant {number}
+ */
 export const TOKEN_REFRESH_BUFFER_MS = 30 * 1000; // 30 seconds
-/** Stream processing configuration */
+
+/**
+ * Stream processing configuration
+ * @namespace
+ */
 export const STREAM_CONFIG = {
     /** Maximum buffer size for SSE pass-through mode (1MB) */
     MAX_BUFFER_SIZE: 1024 * 1024,
 };
-//# sourceMappingURL=constants.js.map

package/dist/lib/logger.js

@@ -1,10 +1,34 @@
+/**
+ * @fileoverview Logging utilities for Qwen OAuth Plugin
+ * Provides configurable logging for debugging and request tracing
+ * @license MIT
+ */
+
 import { writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
-// Logging configuration
+
+/**
+ * Flag to enable request logging to file
+ * Controlled by ENABLE_PLUGIN_REQUEST_LOGGING environment variable
+ * @constant {boolean}
+ */
 export const LOGGING_ENABLED = process.env.ENABLE_PLUGIN_REQUEST_LOGGING === "1";
+
+/**
+ * Flag to enable debug logging to console
+ * Controlled by DEBUG_QWEN_PLUGIN or ENABLE_PLUGIN_REQUEST_LOGGING environment variables
+ * @constant {boolean}
+ */
 export const DEBUG_ENABLED = process.env.DEBUG_QWEN_PLUGIN === "1" || LOGGING_ENABLED;
+
+/**
+ * Directory path for log files
+ * Logs are stored in ~/.opencode/logs/qwen-plugin/
+ * @constant {string}
+ */
 const LOG_DIR = join(homedir(), ".opencode", "logs", "qwen-plugin");
+
 // Log startup message about logging state
 if (LOGGING_ENABLED) {
     console.log("[qwen-oauth-plugin] Request logging ENABLED - logs will be saved to:", LOG_DIR);
@@ -12,23 +36,34 @@ if (LOGGING_ENABLED) {
 if (DEBUG_ENABLED && !LOGGING_ENABLED) {
     console.log("[qwen-oauth-plugin] Debug logging ENABLED");
 }
+
+/**
+ * Request counter for generating unique request IDs in logs
+ * @type {number}
+ */
 let requestCounter = 0;
+
 /**
  * Log request data to file (only when LOGGING_ENABLED is true)
- * @param stage - The stage of the request (e.g., "before-transform", "after-transform")
- * @param data - The data to log
+ * Creates JSON files with request/response data for debugging
+ * @param {string} stage - The stage of the request (e.g., "before-transform", "after-transform", "response")
+ * @param {Object} data - The data to log (request/response objects, metadata, etc.)
+ * @returns {void}
  */
 export function logRequest(stage, data) {
     // Only log if explicitly enabled via environment variable
     if (!LOGGING_ENABLED)
         return;
+    
     // Ensure log directory exists on first log
     if (!existsSync(LOG_DIR)) {
         mkdirSync(LOG_DIR, { recursive: true });
     }
+    
     const timestamp = new Date().toISOString();
     const requestId = ++requestCounter;
     const filename = join(LOG_DIR, `request-${requestId}-${stage}.json`);
+    
     try {
         writeFileSync(filename, JSON.stringify({
             timestamp,
@@ -43,10 +78,13 @@ export function logRequest(stage, data) {
         console.error("[qwen-oauth-plugin] Failed to write log:", error.message);
     }
 }
+
 /**
  * Log debug information (only when DEBUG_ENABLED is true)
- * @param message - Debug message
- * @param data - Optional data to log
+ * Used for detailed debugging during development
+ * @param {string} message - Debug message describing the context
+ * @param {*} [data] - Optional data to log (objects, values, etc.)
+ * @returns {void}
  */
 export function logDebug(message, data) {
     if (!DEBUG_ENABLED)
@@ -58,10 +96,13 @@ export function logDebug(message, data) {
         console.log(`[qwen-oauth-plugin] ${message}`);
     }
 }
+
 /**
  * Log error (always enabled for important issues)
- * @param message - Error message
- * @param data - Optional data to log
+ * Used for critical errors that need attention
+ * @param {string} message - Error message describing what went wrong
+ * @param {*} [data] - Optional data to log (error objects, context, etc.)
+ * @returns {void}
  */
 export function logError(message, data) {
     if (data !== undefined) {
@@ -71,10 +112,13 @@ export function logError(message, data) {
         console.error(`[qwen-oauth-plugin] ${message}`);
     }
 }
+
 /**
  * Log warning (always enabled for important issues)
- * @param message - Warning message
- * @param data - Optional data to log
+ * Used for non-critical issues that may need attention
+ * @param {string} message - Warning message describing the issue
+ * @param {*} [data] - Optional data to log (context, values, etc.)
+ * @returns {void}
  */
 export function logWarn(message, data) {
     if (data !== undefined) {
@@ -84,10 +128,13 @@ export function logWarn(message, data) {
         console.warn(`[qwen-oauth-plugin] ${message}`);
     }
 }
+
 /**
  * Log info message (always enabled)
- * @param message - Info message
- * @param data - Optional data to log
+ * Used for general informational messages
+ * @param {string} message - Info message describing the event
+ * @param {*} [data] - Optional data to log (context, values, etc.)
+ * @returns {void}
  */
 export function logInfo(message, data) {
     if (data !== undefined) {
@@ -97,4 +144,3 @@ export function logInfo(message, data) {
         console.log(`[qwen-oauth-plugin] ${message}`);
     }
 }
-//# sourceMappingURL=logger.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-qwen-cli-auth",
-  "version": "2.2.8",
+  "version": "2.3.0",
   "description": "Qwen OAuth authentication plugin for opencode - use your Qwen account instead of API keys",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",