@toolbaux/guardian 0.1.0

package/dist/extract/ignore.js

@@ -0,0 +1,45 @@
+import path from "node:path";
+export function createIgnoreMatcher(config, baseRoot) {
+    const ignoreDirs = new Set(config.ignore?.directories ?? []);
+    const ignorePaths = normalizeIgnorePaths(config.ignore?.paths ?? [], baseRoot);
+    const isIgnoredPath = (relativePath) => {
+        const normalized = normalizeRelative(relativePath);
+        if (!normalized) {
+            return false;
+        }
+        for (const prefix of ignorePaths) {
+            if (normalized === prefix || normalized.startsWith(`${prefix}/`)) {
+                return true;
+            }
+        }
+        const segments = normalized.split("/").filter(Boolean);
+        return segments.some((segment) => ignoreDirs.has(segment));
+    };
+    const isIgnoredDir = (name, fullPath) => {
+        if (name.startsWith(".")) {
+            return true;
+        }
+        if (ignoreDirs.has(name)) {
+            return true;
+        }
+        const relative = path.relative(baseRoot, fullPath);
+        return isIgnoredPath(relative);
+    };
+    return { isIgnoredDir, isIgnoredPath };
+}
+function normalizeIgnorePaths(paths, baseRoot) {
+    const normalized = new Set();
+    for (const entry of paths) {
+        const resolved = path.isAbsolute(entry) ? path.relative(baseRoot, entry) : entry;
+        const cleaned = normalizeRelative(resolved);
+        if (cleaned) {
+            normalized.add(cleaned);
+        }
+    }
+    return Array.from(normalized);
+}
+function normalizeRelative(relativePath) {
+    const cleaned = relativePath.split(path.sep).join("/");
+    const trimmed = cleaned.startsWith("./") ? cleaned.slice(2) : cleaned;
+    return trimmed.trim();
+}

package/dist/extract/index.js

@@ -0,0 +1,455 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+import { analyzeBackend } from "./analyzers/backend.js";
+import { analyzeFrontend } from "./analyzers/frontend.js";
+import { writeSnapshots } from "./writer.js";
+import { writeDocs } from "./docs.js";
+import { analyzeRuntime } from "./runtime.js";
+import { computeDriftReport, buildFunctionGraph } from "./drift.js";
+import { writeCompressionOutputs } from "./compress.js";
+import { buildCrossStackContracts } from "./contracts.js";
+import { validateArchitectureSnapshot, validateUxSnapshot } from "../schema/index.js";
+import { getOutputLayout } from "../output-layout.js";
+import { logResolvedProjectPaths, resolveProjectPaths } from "../project-discovery.js";
+import { analyzeDepth } from "./analyzers/depth.js";
+export async function buildSnapshots(options) {
+    const startedAt = Date.now();
+    const includeFileGraph = options.includeFileGraph ?? false;
+    const resolvedProject = await resolveProjectPaths({
+        projectRoot: options.projectRoot,
+        backendRoot: options.backendRoot,
+        frontendRoot: options.frontendRoot,
+        configPath: options.configPath
+    });
+    const { workspaceRoot, backendRoot: resolvedBackendRoot, frontendRoot: resolvedFrontendRoot } = resolvedProject;
+    logResolvedProjectPaths(resolvedProject);
+    const reportedBackendRoot = formatOutputPath(resolvedBackendRoot);
+    const reportedFrontendRoot = formatOutputPath(resolvedFrontendRoot);
+    const reportedWorkspaceRoot = formatOutputPath(workspaceRoot);
+    const config = resolvedProject.config;
+    const backend = await analyzeBackend(resolvedBackendRoot, config);
+    const frontend = await analyzeFrontend(resolvedFrontendRoot, config);
+    const projectRoot = workspaceRoot;
+    const runtime = await analyzeRuntime(workspaceRoot, config);
+    const projectName = deriveProjectName(resolvedBackendRoot);
+    const normalizedFrontendCalls = buildFrontendCallIndex(frontend.apiCalls);
+    const unusedEndpoints = backend.endpoints
+        .filter((endpoint) => !isEndpointUsed(endpoint, normalizedFrontendCalls))
+        .map((endpoint) => `${endpoint.method} ${endpoint.path}`)
+        .sort((a, b) => a.localeCompare(b));
+    const dataFlows = buildDataFlows(frontend.uxPages, backend.endpoints, backend.endpointModelUsage);
+    const crossStackContracts = buildCrossStackContracts({
+        endpoints: backend.endpoints,
+        apiCalls: frontend.apiCalls,
+        ux: {
+            version: "0.2",
+            components: frontend.components,
+            component_graph: frontend.componentGraph,
+            pages: frontend.uxPages
+        },
+        dataModels: backend.dataModels
+    });
+    const endpointTestCoverage = buildEndpointTestCoverage(backend.endpoints, backend.testCoverage);
+    const functionTestCoverage = await buildFunctionTestCoverage({
+        backendRoot: resolvedBackendRoot,
+        modules: backend.modules,
+        projectRoot,
+        config,
+        testCoverage: backend.testCoverage
+    });
+    const drift = await computeDriftReport({
+        backendRoot: resolvedBackendRoot,
+        modules: backend.modules,
+        moduleGraph: backend.moduleGraph,
+        fileGraph: backend.fileGraph,
+        circularDependencies: backend.circularDependencies,
+        config,
+        projectRoot
+    });
+    const generatedAt = new Date().toISOString();
+    const extractedTests = [...backend.tests, ...frontend.tests];
+    const architecture = {
+        version: "1.0",
+        metadata: {
+            generated_at: generatedAt,
+            duration_ms: Date.now() - startedAt,
+            target_backend: reportedBackendRoot,
+            target_frontend: reportedFrontendRoot
+        },
+        project: {
+            name: projectName,
+            workspace_root: reportedWorkspaceRoot,
+            backend_root: reportedBackendRoot,
+            frontend_root: reportedFrontendRoot,
+            resolution_source: resolvedProject.resolutionSource,
+            entrypoints: backend.entrypoints
+        },
+        modules: backend.modules,
+        frontend_files: frontend.files,
+        frontend: {
+            pages: frontend.pages,
+            api_calls: frontend.apiCalls
+        },
+        endpoints: backend.endpoints,
+        data_models: backend.dataModels,
+        enums: backend.enums,
+        constants: backend.constants,
+        endpoint_model_usage: backend.endpointModelUsage,
+        cross_stack_contracts: crossStackContracts,
+        tasks: backend.tasks,
+        runtime,
+        data_flows: dataFlows,
+        tests: extractedTests,
+        dependencies: {
+            module_graph: backend.moduleGraph,
+            file_graph: includeFileGraph ? dedupeFileGraph([...backend.fileGraph, ...frontend.fileGraph]) : []
+        },
+        drift,
+        analysis: {
+            circular_dependencies: backend.circularDependencies,
+            orphan_modules: backend.orphanModules,
+            orphan_files: backend.orphanFiles,
+            frontend_orphan_files: frontend.orphanFiles,
+            module_usage: backend.moduleUsage,
+            unused_exports: backend.unusedExports,
+            frontend_unused_exports: frontend.unusedExports,
+            unused_endpoints: unusedEndpoints,
+            frontend_unused_api_calls: frontend.apiCalls
+                .filter((call) => !backend.endpoints.some((ep) => (ep.method.toUpperCase() === "ANY" || ep.method.toUpperCase() === call.method.toUpperCase()) &&
+                normalizePathPattern(ep.path) === normalizePathPattern(call.path)))
+                .map((call) => `${call.method} ${call.path}`),
+            duplicate_functions: backend.duplicateFunctions,
+            similar_functions: backend.similarFunctions,
+            test_coverage: backend.testCoverage,
+            endpoint_test_coverage: endpointTestCoverage,
+            function_test_coverage: functionTestCoverage
+        }
+    };
+    const ux = {
+        version: "0.2",
+        components: frontend.components,
+        component_graph: frontend.componentGraph,
+        pages: frontend.uxPages
+    };
+    validateArchitectureSnapshot(architecture);
+    validateUxSnapshot(ux);
+    return {
+        architecture,
+        ux,
+        projectRoot,
+        config,
+        frontendRoot: resolvedFrontendRoot,
+        backendRoot: resolvedBackendRoot
+    };
+}
+export async function extractProject(options) {
+    const layout = getOutputLayout(options.output);
+    const previous = await loadPreviousSnapshots(layout.machineDir, layout.rootDir);
+    const { architecture, ux, projectRoot, config, backendRoot } = await buildSnapshots(options);
+    const docsMode = options.docsMode ?? config.docs?.mode ?? "lean";
+    const internalDir = config.docs?.internalDir ?? "internal";
+    const result = await writeSnapshots(layout.machineDir, architecture, ux);
+    await writeCompressionOutputs({
+        outputDir: layout.machineDir,
+        architecture,
+        ux,
+        context: {
+            projectRoot,
+            backendRoot,
+            config
+        }
+    });
+    await writeDocs(layout.rootDir, architecture, ux, {
+        projectRoot,
+        driftHistoryPath: config.drift?.historyPath,
+        previous,
+        docsMode,
+        internalDir
+    });
+    // Generate Structural Intelligence reports for the top backend modules
+    const siReports = await generateStructuralIntelligenceReports(architecture);
+    if (siReports.length > 0) {
+        const siPath = path.join(layout.machineDir, "structural-intelligence.json");
+        await fs.writeFile(siPath, JSON.stringify(siReports, null, 2), "utf8");
+        console.log(`Wrote ${siPath}`);
+    }
+    return result;
+}
+async function generateStructuralIntelligenceReports(architecture) {
+    // Pick top modules by any measure of size: endpoints, files, or imports
+    const topModules = architecture.modules
+        .filter((m) => m.files.length > 0 || m.imports.length > 0)
+        .map((m) => ({
+        id: m.id,
+        score: m.endpoints.length * 3 + m.files.length + m.imports.length
+    }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 8)
+        .map((m) => m.id);
+    const reports = [];
+    for (const query of topModules) {
+        try {
+            const report = analyzeDepth({
+                query,
+                modules: architecture.modules,
+                moduleGraph: architecture.dependencies.module_graph,
+                fileGraph: architecture.dependencies.file_graph,
+                circularDependencies: architecture.analysis.circular_dependencies
+            });
+            // Persist any report with a non-trivial subgraph (at least 1 node matched)
+            if (report.structure.nodes > 0) {
+                reports.push(report);
+            }
+        }
+        catch {
+            // Skip modules that error during analysis
+        }
+    }
+    return reports;
+}
+function deriveProjectName(backendRoot) {
+    const base = path.basename(path.resolve(backendRoot));
+    if (base.toLowerCase() === "backend" || base.toLowerCase() === "src") {
+        return path.basename(path.dirname(path.resolve(backendRoot)));
+    }
+    return base || "unknown";
+}
+function formatOutputPath(targetPath) {
+    const relative = path.relative(process.cwd(), targetPath);
+    if (!relative) {
+        return ".";
+    }
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        return targetPath;
+    }
+    return relative.startsWith(".") ? relative : `./${relative}`;
+}
+function dedupeFileGraph(edges) {
+    const seen = new Set();
+    const result = [];
+    for (const edge of edges) {
+        const key = `${edge.from}|${edge.to}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        result.push(edge);
+    }
+    result.sort((a, b) => {
+        const from = a.from.localeCompare(b.from);
+        if (from !== 0)
+            return from;
+        return a.to.localeCompare(b.to);
+    });
+    return result;
+}
+function buildEndpointTestCoverage(endpoints, coverage) {
+    const coverageMap = new Map();
+    for (const entry of coverage.coverage_map) {
+        if (!entry.source_file) {
+            continue;
+        }
+        const current = coverageMap.get(entry.source_file) ?? [];
+        current.push(entry.test_file);
+        coverageMap.set(entry.source_file, current);
+    }
+    return endpoints.map((endpoint) => {
+        const tests = coverageMap.get(endpoint.file) ?? [];
+        return {
+            endpoint: `${endpoint.method} ${endpoint.path}`,
+            method: endpoint.method,
+            path: endpoint.path,
+            file: endpoint.file,
+            covered: tests.length > 0,
+            coverage_type: tests.length > 0 ? "file" : "none",
+            test_files: tests
+        };
+    });
+}
+async function buildFunctionTestCoverage(params) {
+    const { backendRoot, modules, projectRoot, config, testCoverage } = params;
+    const requestedScales = config.drift?.scales ?? [];
+    const shouldBuild = requestedScales.includes("function") ||
+        config.drift?.graphLevel === "function" ||
+        config.drift?.graphLevel === "auto";
+    if (!shouldBuild) {
+        return [];
+    }
+    const fnGraph = await buildFunctionGraph({
+        backendRoot,
+        modules,
+        projectRoot
+    });
+    if (!fnGraph) {
+        return [];
+    }
+    const coverageMap = new Map();
+    for (const entry of testCoverage.coverage_map) {
+        if (!entry.source_file) {
+            continue;
+        }
+        const current = coverageMap.get(entry.source_file) ?? [];
+        current.push(entry.test_file);
+        coverageMap.set(entry.source_file, current);
+    }
+    return fnGraph.nodes.map((node) => {
+        const file = node.split("#")[0] ?? node;
+        const tests = coverageMap.get(file) ?? [];
+        return {
+            function_id: node,
+            file,
+            covered: tests.length > 0,
+            coverage_type: tests.length > 0 ? "file" : "none",
+            test_files: tests
+        };
+    });
+}
+function findCommonRoot(paths) {
+    if (paths.length === 0) {
+        return process.cwd();
+    }
+    const splitPaths = paths.map((entry) => path.resolve(entry).split(path.sep));
+    const minLength = Math.min(...splitPaths.map((parts) => parts.length));
+    const shared = [];
+    for (let i = 0; i < minLength; i += 1) {
+        const segment = splitPaths[0][i];
+        if (splitPaths.every((parts) => parts[i] === segment)) {
+            shared.push(segment);
+        }
+        else {
+            break;
+        }
+    }
+    if (shared.length === 0) {
+        return path.parse(paths[0]).root;
+    }
+    return shared.join(path.sep);
+}
+async function loadPreviousSnapshots(machineDir, rootDir) {
+    const result = {};
+    const candidates = [
+        {
+            archPath: path.join(machineDir, "architecture.snapshot.yaml"),
+            uxPath: path.join(machineDir, "ux.snapshot.yaml")
+        }
+    ];
+    if (rootDir) {
+        candidates.push({
+            archPath: path.join(rootDir, "architecture.snapshot.yaml"),
+            uxPath: path.join(rootDir, "ux.snapshot.yaml")
+        });
+    }
+    for (const candidate of candidates) {
+        if (!result.architecture) {
+            try {
+                const raw = await fs.readFile(candidate.archPath, "utf8");
+                const parsed = yaml.load(raw);
+                if (parsed && typeof parsed === "object") {
+                    result.architecture = parsed;
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+        if (!result.ux) {
+            try {
+                const raw = await fs.readFile(candidate.uxPath, "utf8");
+                const parsed = yaml.load(raw);
+                if (parsed && typeof parsed === "object") {
+                    result.ux = parsed;
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    return result;
+}
+function normalizePathPattern(value) {
+    if (!value) {
+        return "/";
+    }
+    const withoutQuery = value.split("?")[0] ?? value;
+    return withoutQuery
+        .replace(/\$\{[^}]+\}/g, ":param")
+        .replace(/\{[^}]+\}/g, ":param")
+        .replace(/<[^>]+>/g, ":param")
+        .replace(/:\w+/g, ":param")
+        .replace(/\/+/g, "/")
+        .replace(/\/$/, "") || "/";
+}
+function normalizeMethod(method) {
+    return method ? method.toUpperCase() : "GET";
+}
+function buildFrontendCallIndex(calls) {
+    const index = new Map();
+    for (const call of calls) {
+        const pathKey = normalizePathPattern(call.path);
+        const method = normalizeMethod(call.method);
+        const entry = index.get(pathKey) ?? new Set();
+        entry.add(method);
+        index.set(pathKey, entry);
+    }
+    return index;
+}
+function isEndpointUsed(endpoint, index) {
+    const pathKey = normalizePathPattern(endpoint.path);
+    const methods = index.get(pathKey);
+    if (!methods || methods.size === 0) {
+        return false;
+    }
+    if (endpoint.method.toUpperCase() === "ANY") {
+        return true;
+    }
+    return methods.has(endpoint.method.toUpperCase());
+}
+function buildDataFlows(pages, endpoints, endpointUsage) {
+    const endpointByKey = new Map();
+    for (const endpoint of endpoints) {
+        const key = `${normalizeMethod(endpoint.method)} ${normalizePathPattern(endpoint.path)}`;
+        const current = endpointByKey.get(key) ?? [];
+        current.push(endpoint);
+        endpointByKey.set(key, current);
+    }
+    const modelsByEndpoint = new Map();
+    for (const usage of endpointUsage) {
+        modelsByEndpoint.set(usage.endpoint_id, usage.models.map((model) => model.name));
+    }
+    const flows = [];
+    const seen = new Set();
+    for (const page of pages) {
+        for (const call of page.api_calls) {
+            const parts = call.split(" ");
+            if (parts.length < 2) {
+                continue;
+            }
+            const method = normalizeMethod(parts[0]);
+            const pathValue = normalizePathPattern(parts.slice(1).join(" "));
+            const key = `${method} ${pathValue}`;
+            const candidates = endpointByKey.get(key) ?? endpointByKey.get(`ANY ${pathValue}`) ?? [];
+            for (const endpoint of candidates) {
+                const models = modelsByEndpoint.get(endpoint.id) ?? [];
+                const flowKey = `${page.path}|${endpoint.id}|${models.join(",")}`;
+                if (seen.has(flowKey)) {
+                    continue;
+                }
+                seen.add(flowKey);
+                flows.push({
+                    page: page.path,
+                    endpoint_id: endpoint.id,
+                    models
+                });
+            }
+        }
+    }
+    flows.sort((a, b) => {
+        const pageCmp = a.page.localeCompare(b.page);
+        if (pageCmp !== 0)
+            return pageCmp;
+        return a.endpoint_id.localeCompare(b.endpoint_id);
+    });
+    return flows;
+}

package/dist/extract/llm-client.js

@@ -0,0 +1,159 @@
+/**
+ * LLM Client — thin HTTP client for LLM-powered doc generation.
+ *
+ * Resolution order:
+ *   1. Configured LLM  — SPECGUARD_LLM_ENDPOINT + SPECGUARD_LLM_API_KEY both set
+ *   2. Ollama fallback — SPECGUARD_LLM_ENDPOINT/KEY not set, Ollama reachable at localhost
+ *   3. None            — returns null from loadLlmConfig(), callers write placeholder text
+ *
+ * Env vars:
+ *   SPECGUARD_LLM_ENDPOINT   — full URL e.g. https://api.anthropic.com/v1/messages
+ *   SPECGUARD_LLM_API_KEY    — API key (not required for Ollama)
+ *   SPECGUARD_LLM_MODEL      — model ID (optional)
+ *   SPECGUARD_OLLAMA_HOST    — Ollama base URL (default: http://localhost:11434)
+ *   SPECGUARD_OLLAMA_MODEL   — Ollama model (default: llama3.2)
+ *
+ * Wire formats (auto-detected from endpoint URL):
+ *   anthropic  — POST /v1/messages        { model, max_tokens, system, messages }
+ *   openai     — POST /v1/chat/completions { model, max_tokens, messages }
+ *   ollama     — POST /api/chat            { model, stream:false, messages }
+ *
+ * No SDK dependency. Pure fetch.
+ */
+const DEFAULT_CLOUD_MODEL = "claude-haiku-4-5-20251001";
+const DEFAULT_OLLAMA_MODEL = "llama3.2";
+const DEFAULT_OLLAMA_HOST = "http://localhost:11434";
+const DEFAULT_MAX_TOKENS = 2048;
+/**
+ * Load LLM config from environment variables.
+ *
+ * Resolution order:
+ *   1. SPECGUARD_LLM_ENDPOINT + SPECGUARD_LLM_API_KEY → configured cloud/local LLM
+ *   2. Ollama reachable at SPECGUARD_OLLAMA_HOST (or localhost:11434) → Ollama fallback
+ *   3. null → no LLM available
+ */
+export async function loadLlmConfig() {
+    // Priority 1: explicit endpoint + key
+    const endpoint = process.env["SPECGUARD_LLM_ENDPOINT"];
+    const apiKey = process.env["SPECGUARD_LLM_API_KEY"];
+    if (endpoint && apiKey) {
+        const model = process.env["SPECGUARD_LLM_MODEL"] ?? DEFAULT_CLOUD_MODEL;
+        return { endpoint, apiKey, model, provider: detectProvider(endpoint) };
+    }
+    // Priority 2: Ollama fallback
+    const ollamaHost = process.env["SPECGUARD_OLLAMA_HOST"] ?? DEFAULT_OLLAMA_HOST;
+    const ollamaModel = process.env["SPECGUARD_OLLAMA_MODEL"] ?? DEFAULT_OLLAMA_MODEL;
+    if (await isOllamaReachable(ollamaHost)) {
+        return {
+            endpoint: `${ollamaHost}/api/chat`,
+            apiKey: "",
+            model: ollamaModel,
+            provider: "ollama",
+        };
+    }
+    return null;
+}
+/**
+ * Synchronous version — only checks env vars, does NOT probe Ollama.
+ * Use when async is not possible, or when you want to skip Ollama discovery.
+ */
+export function loadLlmConfigSync() {
+    const endpoint = process.env["SPECGUARD_LLM_ENDPOINT"];
+    const apiKey = process.env["SPECGUARD_LLM_API_KEY"];
+    if (!endpoint || !apiKey)
+        return null;
+    const model = process.env["SPECGUARD_LLM_MODEL"] ?? DEFAULT_CLOUD_MODEL;
+    return { endpoint, apiKey, model, provider: detectProvider(endpoint) };
+}
+/**
+ * Send messages to the LLM and return the response text.
+ * Throws on HTTP errors.
+ */
+export async function llmComplete(config, messages, maxTokens = DEFAULT_MAX_TOKENS) {
+    const headers = {
+        "Content-Type": "application/json",
+    };
+    let body;
+    if (config.provider === "anthropic") {
+        headers["x-api-key"] = config.apiKey;
+        headers["anthropic-version"] = "2023-06-01";
+        body = buildAnthropicBody(config.model, messages, maxTokens);
+    }
+    else if (config.provider === "ollama") {
+        // Ollama: no auth header needed
+        body = buildOllamaBody(config.model, messages);
+    }
+    else {
+        // openai-compatible
+        if (config.apiKey)
+            headers["Authorization"] = `Bearer ${config.apiKey}`;
+        body = buildOpenAIBody(config.model, messages, maxTokens);
+    }
+    const response = await fetch(config.endpoint, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => "(no body)");
+        throw new Error(`LLM request failed [${config.provider}]: ${response.status} ${response.statusText} — ${text}`);
+    }
+    const data = await response.json();
+    return extractText(config.provider, data);
+}
+// ── Format detection ──────────────────────────────────────────────────────
+function detectProvider(endpoint) {
+    const lower = endpoint.toLowerCase();
+    if (lower.includes("anthropic") || lower.includes("/v1/messages"))
+        return "anthropic";
+    if (lower.includes("/api/chat") || lower.includes("11434"))
+        return "ollama";
+    return "openai";
+}
+// ── Body builders ─────────────────────────────────────────────────────────
+function buildAnthropicBody(model, messages, maxTokens) {
+    const systemMessages = messages.filter((m) => m.role === "system");
+    const nonSystemMessages = messages.filter((m) => m.role !== "system");
+    const systemText = systemMessages.map((m) => m.content).join("\n\n");
+    const body = {
+        model,
+        max_tokens: maxTokens,
+        messages: nonSystemMessages,
+    };
+    if (systemText)
+        body["system"] = systemText;
+    return body;
+}
+function buildOpenAIBody(model, messages, maxTokens) {
+    return { model, max_tokens: maxTokens, messages };
+}
+function buildOllamaBody(model, messages) {
+    return { model, stream: false, messages };
+}
+// ── Response extraction ───────────────────────────────────────────────────
+function extractText(provider, data) {
+    if (provider === "anthropic") {
+        const content = data["content"] ?? [];
+        return content.find((c) => c.type === "text")?.text ?? "";
+    }
+    if (provider === "ollama") {
+        const message = data["message"];
+        return message?.content ?? "";
+    }
+    // openai
+    const choices = data["choices"] ?? [];
+    return choices[0]?.message?.content ?? "";
+}
+// ── Ollama availability probe ─────────────────────────────────────────────
+async function isOllamaReachable(host) {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 1500);
+        const res = await fetch(`${host}/api/tags`, { signal: controller.signal });
+        clearTimeout(timeout);
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}