📝 Add docstrings to release/review-comments

lib/auth/server.ts

@@ -10,9 +10,14 @@
 const successHtml = fs.readFileSync(path.join(__dirname, "..", "oauth-success.html"), "utf-8");
 
 /**
- * Start a small local HTTP server that waits for /auth/callback and returns the code
- * @param options - OAuth state for validation
- * @returns Promise that resolves to server info
+ * Start a local HTTP listener that captures the OAuth authorization code from /auth/callback.
+ *
+ * @param options - Configuration object.
+ * @param options.state - Expected `state` query parameter value used to validate the callback.
+ * @returns An object containing:
+ *  - `port`: the bound port number (1455),
+ *  - `close()`: a function that closes the server,
+ *  - `waitForCode(expectedState?)`: a function that waits up to ~60 seconds for an authorization code; returns `{ code: string }` when a code is captured (and matches the configured state), or `null` if no code is received within the timeout.
  */
 export function startLocalOAuthServer({ state }: { state: string }): Promise<OAuthServerInfo> {
 	const server = http.createServer((req, res) => {
@@ -53,7 +58,7 @@
 				resolve({
 					port: 1455,
 					close: () => server.close(),
 					waitForCode: async (expectedState?: string) => {
 						const poll = () => new Promise<void>((r) => setTimeout(r, 100));
 						for (let i = 0; i < 600; i++) {
 							const lastCode = (server as http.Server & { _lastCode?: string })._lastCode;
@@ -77,4 +82,4 @@
 				});
 			});
 	});
-}
+}

lib/logger.ts

@@ -143,6 +143,18 @@ function emit(level: LogLevel, message: string, extra?: Record<string, unknown>)
 	logToConsole(level, message, sanitizedExtra);
 }
 
+/**
+ * Sends a user-facing notification (toast) through the configured logger client, if available.
+ *
+ * Constructs a payload with a title derived from the log level, the provided message as the body,
+ * and optional extra metadata, then attempts to call `app.notify` or `app.toast`. If no app or
+ * compatible send method is present, the function returns without action. Failures to send are
+ * recorded as a warning via console logging.
+ *
+ * @param level - The severity level for the notification (`"debug" | "info" | "warn" | "error"`). A value of `"error"` produces an "error" title; other values produce a "warning" title.
+ * @param message - The primary text to show in the notification body.
+ * @param extra - Optional metadata to include with the notification payload.
+ */
 function notifyToast(level: LogLevel, message: string, extra?: Record<string, unknown>): void {
 	const app = (loggerClient as any)?.app;
 	if (!app) return;
@@ -165,6 +177,15 @@ function notifyToast(level: LogLevel, message: string, extra?: Record<string, un
 	});
 }
 
+/**
+ * Writes a plugin-prefixed log message to the console when the log level is applicable.
+ *
+ * Logs warnings and errors unconditionally; debug and info messages are written only when console logging is enabled. The message is prefixed with the plugin name and, if provided, `extra` is JSON-stringified and appended; on JSON serialization failure, `String(extra)` is appended instead.
+ *
+ * @param level - Log level determining severity and console method
+ * @param message - Primary log message text
+ * @param extra - Additional context appended to the message; values are JSON-stringified when possible
+ */
 function logToConsole(level: LogLevel, message: string, extra?: Record<string, unknown>): void {
 	const isWarnOrError = level === "warn" || level === "error";
 	const shouldLogDebugOrInfo = CONSOLE_LOGGING_ENABLED && (level === "debug" || level === "info");
@@ -360,4 +381,4 @@ function toErrorMessage(error: unknown): string {
 		return error.message;
 	}
 	return String(error);
-}
+}

lib/request/fetch-helpers.ts

@@ -108,7 +108,7 @@
  * @param codexMode - Enable CODEX_MODE (bridge prompt instead of tool remap)
  * @returns Transformed body and updated init, or undefined if no body
  */
 export async function transformRequestForCodex(
 	init: RequestInit | undefined,
 	url: string,
 	codexInstructions: string,
@@ -248,11 +248,12 @@
 }
 
 /**
- * Handles error responses from the Codex API
- * @param response - Error response from API
- * @returns Response with error details
+ * Enriches a Codex API error Response with structured error details and rate-limit metadata.
+ *
+ * @param response - The original error Response from a Codex API request
+ * @returns A Response with the same status and statusText whose body is either the original raw body or a JSON object containing an `error` object with `message`, optional `friendly_message`, optional `rate_limits`, and `status`. When the body is enriched, the response `Content-Type` is set to `application/json; charset=utf-8`.
  */
 export async function handleErrorResponse(response: Response): Promise<Response> {
 	const raw = await response.text();
 
 	let enriched = raw;
@@ -368,4 +369,4 @@
 	if (v == null) return undefined;
 	const n = parseInt(v, 10);
 	return Number.isFinite(n) ? n : undefined;
-}
+}