fix(opencode-go): address CodeRabbit review — defensive validation, stronger assertions, JSDoc (#172)

- Add Array.isArray guard + per-model safeParse with console.warn in getOpencodeGoModels
- Assert max_completion_tokens and temperature in handler tests
- Add test cases for non-array response.data.data and invalid model entries
- Add JSDoc with @param/@returns to all public functions

Author: proyectoauraorg

src/api/providers/__tests__/opencode-go.spec.ts

@@ -147,6 +147,8 @@ describe("OpencodeGoHandler", () => {
 					model: "glm-5.1",
 					stream: true,
 					stream_options: { include_usage: true },
+					max_completion_tokens: 32768,
+					temperature: expect.any(Number),
 				}),
 			)
 		})
@@ -157,7 +159,13 @@ describe("OpencodeGoHandler", () => {
 			mockCreate.mockResolvedValue({ choices: [{ message: { content: "the answer" } }] })
 			const handler = new OpencodeGoHandler(mockOptions)
 			expect(await handler.completePrompt("ping")).toBe("the answer")
-			expect(mockCreate).toHaveBeenCalledWith(expect.objectContaining({ model: "glm-5.1", stream: false }))
+			expect(mockCreate).toHaveBeenCalledWith(
+				expect.objectContaining({
+					model: "glm-5.1",
+					stream: false,
+					max_completion_tokens: 32768,
+				}),
+			)
 		})
 
 		it("wraps errors with an Opencode Go-specific message", async () => {

src/api/providers/fetchers/__tests__/opencode-go.spec.ts

@@ -64,6 +64,31 @@ describe("Opencode Go Fetchers", () => {
 			mockedAxios.get.mockRejectedValue(new Error("network"))
 			expect(await getOpencodeGoModels("k")).toEqual({})
 		})
+
+		it("falls back to an empty array when response.data.data is not an array", async () => {
+			mockedAxios.get.mockResolvedValue({ data: { data: null } })
+			expect(await getOpencodeGoModels("k")).toEqual({})
+		})
+
+		it("skips entries that fail safeParse with a console.warn", async () => {
+			mockedAxios.get.mockResolvedValue({
+				data: {
+					data: [
+						{ id: "valid-model", context_window: 50000 },
+						{ not_a_field: true }, // no `id` — will fail safeParse
+					],
+				},
+			})
+			const warnSpy = vitest.spyOn(console, "warn").mockImplementation(() => {})
+
+			const models = await getOpencodeGoModels("k")
+
+			expect(Object.keys(models)).toEqual(["valid-model"])
+			expect(warnSpy).toHaveBeenCalledTimes(1)
+			expect(warnSpy.mock.calls[0][0]).toContain("Skipping invalid Opencode Go model entry")
+
+			warnSpy.mockRestore()
+		})
 	})
 
 	describe("parseOpencodeGoModel", () => {

src/api/providers/fetchers/opencode-go.ts

@@ -29,6 +29,16 @@ const opencodeGoModelsResponseSchema = z.object({
 	data: z.array(opencodeGoModelSchema),
 })
 
+/**
+ * Maps a raw Opencode Go model entry to the internal {@link ModelInfo} shape.
+ *
+ * Falls back to {@link opencodeGoDefaultModelInfo} when the upstream payload
+ * omits context-window or max-token fields, ensuring downstream consumers
+ * always receive a fully-populated object.
+ *
+ * @param model - Validated model entry from the `/models` response.
+ * @returns Normalised model metadata suitable for the model picker.
+ */
 export const parseOpencodeGoModel = (model: OpencodeGoModel): ModelInfo => ({
 	maxTokens: model.max_output_tokens ?? model.max_tokens ?? opencodeGoDefaultModelInfo.maxTokens,
 	contextWindow: model.context_window ?? model.context_length ?? opencodeGoDefaultModelInfo.contextWindow,
@@ -37,6 +47,17 @@ export const parseOpencodeGoModel = (model: OpencodeGoModel): ModelInfo => ({
 	description: model.description ?? model.name,
 })
 
+/**
+ * Fetches the list of available models from the Opencode Go `/models` endpoint.
+ *
+ * The endpoint shape mirrors the OpenAI `/models` response. A permissive Zod
+ * schema is used so that unknown fields are silently dropped rather than
+ * causing a hard failure. Invalid entries (e.g. missing `id`) are skipped
+ * with a console warning rather than propagated to the UI.
+ *
+ * @param apiKey - Optional Bearer token for authenticated requests.
+ * @returns A record mapping model IDs to their normalised {@link ModelInfo}.
+ */
 export async function getOpencodeGoModels(apiKey?: string): Promise<Record<string, ModelInfo>> {
 	const models: Record<string, ModelInfo> = {}
 
@@ -47,16 +68,20 @@ export async function getOpencodeGoModels(apiKey?: string): Promise<Record<strin
 		})
 
 		const result = opencodeGoModelsResponseSchema.safeParse(response.data)
-		const data = result.success ? result.data.data : (response.data?.data ?? [])
+		const rawData = result.success ? result.data.data : response.data?.data
+		const data = Array.isArray(rawData) ? rawData : []
 
 		if (!result.success) {
 			console.error(`Opencode Go models response is invalid: ${JSON.stringify(result.error.format())}`)
 		}
 
-		for (const model of data) {
-			if (model?.id) {
-				models[model.id] = parseOpencodeGoModel(model)
+		for (const rawModel of data) {
+			const parsed = opencodeGoModelSchema.safeParse(rawModel)
+			if (!parsed.success) {
+				console.warn(`Skipping invalid Opencode Go model entry: ${JSON.stringify(rawModel)}`)
+				continue
 			}
+			models[parsed.data.id] = parseOpencodeGoModel(parsed.data)
 		}
 	} catch (error) {
 		console.error(`Error fetching Opencode Go models: ${error instanceof Error ? error.message : String(error)}`)

src/api/providers/opencode-go.ts

@@ -12,14 +12,22 @@ import type { SingleCompletionHandler, ApiHandlerCreateMessageMetadata } from ".
 import { RouterProvider } from "./router-provider"
 
 /**
- * Opencode "Go" plan — OpenAI-compatible gateway (https://opencode.ai/zen/go/v1).
+ * API handler for the Opencode "Go" subscription plan.
+ *
+ * Routes requests through the OpenAI-compatible gateway at
+ * `https://opencode.ai/zen/go/v1`, delegating model resolution and streaming
+ * logic to the shared {@link RouterProvider} base class.
  *
  * Exposes the Go subscription's models as a first-class provider with a dynamic
  * model list (fetched from `/v1/models`) so users can switch models on the fly,
  * instead of configuring each one manually as a separate OpenAI-Compatible
  * provider (#172).
+ *
+ * Supports text generation, reasoning content (GLM/DeepSeek), tool calls,
+ * and non-streaming prompt completion.
  */
 export class OpencodeGoHandler extends RouterProvider implements SingleCompletionHandler {
+	/** Creates a new handler bound to the user's Go API key and selected model. */
 	constructor(options: ApiHandlerOptions) {
 		super({
 			options,
@@ -32,6 +40,10 @@ export class OpencodeGoHandler extends RouterProvider implements SingleCompletio
 		})
 	}
 
+	/**
+	 * Streams a chat completion response, yielding typed chunks for text,
+	 * reasoning, partial tool calls, and token usage.
+	 */
 	override async *createMessage(
 		systemPrompt: string,
 		messages: Anthropic.Messages.MessageParam[],
@@ -96,6 +108,13 @@ export class OpencodeGoHandler extends RouterProvider implements SingleCompletio
 		}
 	}
 
+	/**
+	 * Performs a non-streaming chat completion and returns the full response text.
+	 *
+	 * @param prompt - The user prompt to send as a single user message.
+	 * @returns The model's reply text, or an empty string if no content is returned.
+	 * @throws Error with an Opencode Go-specific prefix if the request fails.
+	 */
 	async completePrompt(prompt: string): Promise<string> {
 		const { id: modelId, info } = await this.fetchModel()