feat: add opt-in feedback transport

Author: whut09

src/context-registry/feedback-transport.ts

@@ -0,0 +1,38 @@
+import type { ContextFeedbackConfig } from "../core/types.js";
+import type { ContextFeedback } from "./types.js";
+
+export type ContextFeedbackTransportStatus = "disabled" | "sent" | "failed";
+
+export interface ContextFeedbackTransportResult {
+  status: ContextFeedbackTransportStatus;
+  endpoint?: string;
+  error?: string;
+}
+
+export async function submitContextFeedback(
+  feedback: ContextFeedback,
+  config: ContextFeedbackConfig,
+  options: { timeoutMs?: number; fetcher?: typeof fetch } = {}
+): Promise<ContextFeedbackTransportResult> {
+  if (!config.enabled || !config.network || !config.telemetry || !config.endpoint) {
+    return { status: "disabled", ...(config.endpoint ? { endpoint: config.endpoint } : {}) };
+  }
+  const fetcher = options.fetcher ?? globalThis.fetch;
+  if (!fetcher) return { status: "failed", endpoint: config.endpoint, error: "The runtime does not provide fetch." };
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 10_000);
+  try {
+    const response = await fetcher(config.endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(feedback),
+      signal: controller.signal
+    });
+    if (!response.ok) return { status: "failed", endpoint: config.endpoint, error: "Feedback endpoint returned HTTP " + response.status + "." };
+    return { status: "sent", endpoint: config.endpoint };
+  } catch (error) {
+    return { status: "failed", endpoint: config.endpoint, error: error instanceof Error ? error.message : String(error) };
+  } finally {
+    clearTimeout(timeout);
+  }
+}

src/context-registry/index.ts

@@ -16,3 +16,4 @@ export * from "./annotations.js";
 export * from "./feedback.js";
 export * from "./feedback-store.js";
 export * from "./feedback-stats.js";
+export * from "./feedback-transport.js";

test/context-feedback-transport.test.ts

@@ -0,0 +1,55 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createContextFeedback } from "../src/context-registry/feedback.js";
+import { submitContextFeedback } from "../src/context-registry/feedback-transport.js";
+
+const feedback = createContextFeedback({
+  repository: "C:/work/project",
+  entryId: "official/payments",
+  source: "official",
+  version: "2.0.0",
+  revision: 1,
+  target: "entry",
+  label: "useful"
+});
+
+test("feedback transport is offline by default and does not call fetch", async () => {
+  let calls = 0;
+  const result = await submitContextFeedback(
+    feedback,
+    { enabled: true, telemetry: false, network: false, useLocalQualitySignals: false },
+    { fetcher: async () => { calls += 1; throw new Error("must not call"); } }
+  );
+  assert.equal(result.status, "disabled");
+  assert.equal(calls, 0);
+});
+
+test("feedback transport sends only explicit safe metadata", async () => {
+  let body = "";
+  const result = await submitContextFeedback(
+    feedback,
+    { enabled: true, telemetry: true, network: true, useLocalQualitySignals: false, endpoint: "https://feedback.example.test/v1" },
+    {
+      fetcher: async (_input, init) => {
+        body = String(init?.body);
+        return new Response(null, { status: 204 });
+      }
+    }
+  );
+  assert.equal(result.status, "sent");
+  const payload = JSON.parse(body) as Record<string, unknown>;
+  assert.equal(payload.entryId, "official/payments");
+  assert.equal("task" in payload, false);
+  assert.equal("content" in payload, false);
+  assert.equal("repository" in payload, false);
+});
+
+test("network failure is returned without throwing", async () => {
+  const result = await submitContextFeedback(
+    feedback,
+    { enabled: true, telemetry: true, network: true, useLocalQualitySignals: false, endpoint: "https://feedback.example.test/v1" },
+    { fetcher: async () => { throw new Error("offline"); } }
+  );
+  assert.equal(result.status, "failed");
+  assert.match(result.error ?? "", /offline/);
+});