test(knowledge): add smoke script and OpenAPI contract test

Expose npm run smoke:knowledge for health + openapi + POST /v1/search.
Add offline vitest asserting knowledge-v1.yaml includes v1 paths.

Made-with: Cursor

Author: ilyar

package.json

@@ -8,6 +8,7 @@
     "start": "node dist/index.js",
     "dev": "tsx --env-file=.env src/index.ts",
     "test": "vitest run",
+    "smoke:knowledge": "node scripts/smoke-knowledge-search.mjs",
     "bot": "node --env-file=.env dist/bot/polling.js",
     "bot:dev": "tsx --env-file=.env src/bot/polling.ts",
     "apply-branding": "tsx --env-file=.env src/bot/apply-branding.ts",

scripts/smoke-knowledge-search.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * Primitive smoke test for public knowledge API (behind Caddy).
+ *
+ * Env:
+ *   KNOWLEDGE_SMOKE_BASE   — default https://spawn-dock.w3voice.net/knowledge
+ *   KNOWLEDGE_SMOKE_TOKEN — optional Bearer (same as API_TOKEN / Telegram /gettoken)
+ *   API_TOKEN             — used if KNOWLEDGE_SMOKE_TOKEN unset
+ *
+ * After rotating Qwen OAuth on the host/GitHub, redeploy so `search` receives fresh
+ * `PROD_QWEN_OAUTH_CREDS` / `QWEN_OAUTH_CREDS_B64` in `.env`.
+ */
+const base = (process.env.KNOWLEDGE_SMOKE_BASE || "https://spawn-dock.w3voice.net/knowledge").replace(
+  /\/$/,
+  "",
+);
+const token = (process.env.KNOWLEDGE_SMOKE_TOKEN || process.env.API_TOKEN || "").trim();
+
+async function mustOk(label, res, previewLen = 500) {
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`${label} HTTP ${res.status}: ${text.slice(0, previewLen)}`);
+  }
+  return text;
+}
+
+async function main() {
+  const healthRes = await fetch(`${base}/api/v1/health`);
+  await mustOk("GET /api/v1/health", healthRes);
+
+  const openapiRes = await fetch(`${base}/openapi.yaml`);
+  const yaml = await mustOk("GET /openapi.yaml", openapiRes, 200);
+  if (!yaml.includes("/v1/search")) {
+    throw new Error("openapi.yaml missing /v1/search");
+  }
+
+  const headers = { "content-type": "application/json" };
+  if (token) {
+    headers.authorization = `Bearer ${token}`;
+  }
+
+  const searchRes = await fetch(`${base}/api/v1/search`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ query: "SpawnDock TMA", locale: "en" }),
+  });
+  const body = await searchRes.text();
+  if (!searchRes.ok) {
+    throw new Error(`POST /api/v1/search HTTP ${searchRes.status}: ${body.slice(0, 2000)}`);
+  }
+  let json;
+  try {
+    json = JSON.parse(body);
+  } catch {
+    throw new Error("search response is not JSON");
+  }
+  if (typeof json.answer !== "string" || json.answer.length === 0) {
+    throw new Error('search response missing non-empty "answer"');
+  }
+
+  console.log(
+    JSON.stringify({
+      ok: true,
+      base,
+      bearer: token ? "yes" : "no",
+      answerPreview: json.answer.slice(0, 120),
+    }),
+  );
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});

src/__tests__/knowledge-openapi-contract.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Offline check: OpenAPI file matches PRD paths (no network). */
+describe("knowledge OpenAPI contract", () => {
+  it("contains v1 health and search paths", () => {
+    const p = resolve(__dirname, "../../openapi/knowledge-v1.yaml");
+    const yaml = readFileSync(p, "utf8");
+    expect(yaml).toContain("/v1/health");
+    expect(yaml).toContain("/v1/search");
+    expect(yaml).toContain("servers:");
+    expect(yaml).toContain("/knowledge/api");
+  });
+});