Improve doctor diagnostics

Author: itsflaid

PRD.md

@@ -414,7 +414,7 @@ DevMap version    0.1.0               ✓
 Node.js version   20.11.0             ✓
 Provider          Groq                ✓
 API key           valid               ✓
-Model             qwen-2.5-coder-32b  ✓
+Model             openai/gpt-oss-20b  ✓
 Snapshot          exists              ✓
 
 No issues found.

docs/for-me-personal/PROGRESS.md

@@ -61,7 +61,19 @@ Terakhir diperbarui: 2026-06-11
   baru.
 - `--fresh` memaksa static analysis dan AI interpretation baru.
 - Jika AI gagal, static analysis dan snapshot tetap berhasil.
-- Automated test saat ini berjumlah 29 dan seluruhnya lulus.
+- Automated test AI memakai mock provider dan tidak menggunakan quota.
+
+### Doctor Diagnostics
+
+- `devmap doctor` sekarang menampilkan versi DevMap, Node.js, OS/arsitektur,
+  lokasi project, framework, package manager, provider, config, dan snapshot.
+- Node.js di bawah versi 18 ditandai sebagai unsupported.
+- Model `auto` di-resolve ke model aktual `openai/gpt-oss-20b`.
+- API key divalidasi melalui endpoint daftar model Groq.
+- Availability selected model ikut diperiksa.
+- Snapshot dibedakan menjadi valid, missing, corrupt, dan unsupported schema.
+- API key dan raw stack trace tidak pernah ditampilkan.
+- Automated test saat ini berjumlah 32 dan seluruhnya lulus.
 
 ### Cross-Platform CI
 
@@ -87,9 +99,9 @@ Terakhir diperbarui: 2026-06-11
 ### Prioritas Berikutnya
 
 1. Pastikan rerun GitHub Actions hijau pada seluruh 9 kombinasi.
-2. Tingkatkan `doctor` untuk memvalidasi provider dan selected model.
+2. Rapikan package npm dan verifikasi tarball sebelum publish.
 3. Tambahkan streaming output untuk jawaban AI.
-4. Rapikan package npm dan verifikasi tarball sebelum publish.
+4. Lakukan manual verification Groq pada project nyata.
 
 ## Status Saat Ini
 

docs/for-me-personal/TEST.md

@@ -78,8 +78,8 @@ Saat ini test mencakup:
 Hasil minimum yang diharapkan:
 
 ```text
-tests 29
-pass 29
+tests 32
+pass 32
 fail 0
 ```
 
@@ -120,8 +120,8 @@ npx -p node@20 node packages\cli\node_modules\tsx\dist\cli.mjs packages\cli\test
 Hasil minimum yang diharapkan untuk keduanya:
 
 ```text
-tests 29
-pass 29
+tests 32
+pass 32
 fail 0
 ```
 
@@ -187,6 +187,27 @@ Pastikan:
 - `--deep --fresh` memakai model deep analysis;
 - static snapshot tetap tersimpan jika Groq gagal.
 
+## Testing `devmap doctor`
+
+Jalankan automated test dan hasil build:
+
+```powershell
+pnpm test:cli
+pnpm build:cli
+node packages\cli\dist\index.js doctor
+```
+
+Pastikan output menampilkan:
+
+- versi DevMap dan Node.js;
+- OS dan arsitektur;
+- lokasi project, framework, dan package manager;
+- provider, status API key, dan selected model;
+- status snapshot;
+- warning actionable ketika config, key, model, atau snapshot bermasalah.
+
+API key asli dan raw stack trace tidak boleh muncul pada output.
+
 ## GitHub Actions
 
 Workflow:

packages/cli/src/ai/groq.ts

@@ -23,6 +23,11 @@ export type GroqClientDependencies = {
   sleep?: (milliseconds: number) => Promise<void>;
 };
 
+export type GroqProviderInspection = {
+  reachable: true;
+  modelAvailable: boolean;
+};
+
 export class GroqClient implements AiClient {
   private readonly fetchImplementation: typeof fetch;
   private readonly sleep: (milliseconds: number) => Promise<void>;
@@ -130,10 +135,19 @@ export class GroqClient implements AiClient {
 }
 
 export async function validateGroqApiKey(apiKey: string): Promise<void> {
+  await inspectGroqProvider(apiKey);
+}
+
+export async function inspectGroqProvider(
+  apiKey: string,
+  model?: string,
+  dependencies: Pick<GroqClientDependencies, "fetch"> = {}
+): Promise<GroqProviderInspection> {
+  const fetchImplementation = dependencies.fetch ?? fetch;
   let response: Response;
 
   try {
-    response = await fetch(GROQ_MODELS_URL, {
+    response = await fetchImplementation(GROQ_MODELS_URL, {
       headers: {
         Authorization: `Bearer ${apiKey}`
       }
@@ -158,6 +172,12 @@ export async function validateGroqApiKey(apiKey: string): Promise<void> {
       "Try again shortly or check https://status.groq.com."
     );
   }
+
+  const modelIds = await readModelIds(response);
+  return {
+    reachable: true,
+    modelAvailable: !model || modelIds.includes(model)
+  };
 }
 
 type GroqCompletionPayload = {
@@ -265,3 +285,20 @@ function normalizeUsage(usage: NonNullable<GroqCompletionPayload["usage"]>): AiT
 function wait(milliseconds: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, milliseconds));
 }
+
+async function readModelIds(response: Response): Promise<string[]> {
+  try {
+    const payload = await response.json() as {
+      data?: Array<{ id?: unknown }>;
+    };
+
+    return (payload.data ?? [])
+      .map((model) => model.id)
+      .filter((id): id is string => typeof id === "string");
+  } catch {
+    throw new DevmapError(
+      "Groq returned an unreadable model list.",
+      "Try again shortly or check https://status.groq.com."
+    );
+  }
+}

packages/cli/src/commands/doctor.ts

@@ -1,23 +1,110 @@
-import { existsSync } from "node:fs";
-import { readConfig, getConfigPath } from "../utils/config.js";
-import { getSnapshotPath } from "../cache/snapshot.js";
+import { arch, platform } from "node:os";
+import { resolve } from "node:path";
+import {
+  DEFAULT_AI_MODELS,
+  inspectGroqProvider,
+  type GroqProviderInspection
+} from "../ai/groq.js";
+import { scanFiles } from "../analyzers/fileScanner.js";
+import { detectFramework } from "../analyzers/frameworkDetector.js";
+import { detectProjectMetadata } from "../analyzers/projectMetadata.js";
+import { inspectSnapshot } from "../cache/snapshot.js";
+import { readConfig, type DevmapConfig } from "../utils/config.js";
+import { DevmapError } from "../utils/errors.js";
 import { output } from "../utils/output.js";
 
-export async function doctorCommand(): Promise<void> {
-  const config = await readConfig();
+const DEVMAP_VERSION = "0.1.0";
+const MINIMUM_NODE_MAJOR = 18;
+
+export type DoctorDependencies = {
+  projectRoot?: string;
+  loadConfig?: () => Promise<DevmapConfig | null>;
+  inspectProvider?: (
+    apiKey: string,
+    model: string
+  ) => Promise<GroqProviderInspection>;
+};
+
+export async function doctorCommand(
+  dependencies: DoctorDependencies = {}
+): Promise<void> {
+  const projectRoot = resolve(dependencies.projectRoot ?? process.cwd());
+  const loadConfig = dependencies.loadConfig ?? readConfig;
+  const inspectProvider = dependencies.inspectProvider ?? inspectGroqProvider;
+  const [config, snapshotResult, files] = await Promise.all([
+    loadConfig(),
+    inspectSnapshot(projectRoot),
+    scanFiles(projectRoot)
+  ]);
+  const framework = detectFramework(files);
+  const project = detectProjectMetadata(projectRoot, framework, files);
+  const selectedModel = config?.model === "auto"
+    ? DEFAULT_AI_MODELS.ask
+    : config?.model;
+  const issues: string[] = [];
+  const nodeSupported = readNodeMajor(process.version) >= MINIMUM_NODE_MAJOR;
 
   output.section("DevMap Doctor");
-  output.keyValue("Node.js", process.version);
+  output.keyValue("DevMap", DEVMAP_VERSION);
+  output.keyValue("Node.js", `${process.version} (${nodeSupported ? "supported" : "unsupported"})`);
+  output.keyValue("OS", `${platform()}/${arch()}`);
+  output.keyValue("Project", project.name);
+  output.keyValue("Framework", framework);
+  output.keyValue("Package Manager", project.packageManager);
   output.keyValue("Provider", config?.provider ?? "not configured");
-  output.keyValue("API key", config?.apiKey ? "set" : "not set");
-  output.keyValue("Config", existsSync(getConfigPath()) ? "exists" : "missing");
-  output.keyValue("Snapshot", existsSync(getSnapshotPath(process.cwd())) ? "exists" : "missing");
+  output.keyValue("Config", config ? "exists" : "missing");
+  output.keyValue("Snapshot", snapshotResult.status);
 
   if (!config) {
-    output.warning("Run devmap init to create ~/.devmap/config.json");
-  } else if (!config.apiKey) {
-    output.warning("Groq API key is not set yet. Add it before Phase 2 AI commands.");
+    issues.push("Run devmap init to create ~/.devmap/config.json.");
+    output.keyValue("API key", "not configured");
+    output.keyValue("Model", "not configured");
+  } else if (!config.apiKey || !selectedModel) {
+    issues.push("Run devmap init again to configure Groq.");
+    output.keyValue("API key", "missing");
+    output.keyValue("Model", selectedModel ?? "not configured");
   } else {
-    output.success("Base configuration looks ready");
+    try {
+      const provider = await inspectProvider(config.apiKey, selectedModel);
+      output.keyValue("API key", provider.reachable ? "valid" : "unreachable");
+      output.keyValue(
+        "Model",
+        provider.modelAvailable ? selectedModel : `unavailable: ${selectedModel}`
+      );
+
+      if (!provider.modelAvailable) {
+        issues.push("Run devmap init or choose an available Groq model.");
+      }
+    } catch (error) {
+      const message = error instanceof DevmapError
+        ? error.message
+        : "Provider diagnostics failed.";
+      output.keyValue("API key", "invalid or unreachable");
+      output.keyValue("Model", selectedModel);
+      issues.push(message);
+    }
+  }
+
+  if (!nodeSupported) {
+    issues.push(`Install Node.js ${MINIMUM_NODE_MAJOR} or newer.`);
+  }
+
+  if (snapshotResult.status === "corrupt" || snapshotResult.status === "unsupported") {
+    issues.push("Run devmap analyze --fresh to regenerate the snapshot.");
   }
+
+  if (issues.length === 0) {
+    output.success("No issues found");
+    return;
+  }
+
+  output.section("Issues");
+  for (const issue of issues) {
+    output.warning(issue);
+  }
+}
+
+function readNodeMajor(version: string): number {
+  const match = version.match(/^v?(\d+)/);
+  return match ? Number(match[1]) : 0;
 }