@luckystack/test-runner 0.1.0

package/dist/index.js

@@ -0,0 +1,1270 @@
+// src/walkEndpoints.ts
+var walkEndpoints = (apiMethodMap) => {
+  const endpoints = [];
+  for (const [page, nameMap] of Object.entries(apiMethodMap)) {
+    if (!nameMap) continue;
+    for (const [name, versionMap] of Object.entries(nameMap)) {
+      if (!versionMap) continue;
+      for (const [version, method] of Object.entries(versionMap)) {
+        if (method === void 0) continue;
+        endpoints.push({
+          page,
+          name,
+          version,
+          method,
+          fullPath: `api/${page}/${name}/${version}`
+        });
+      }
+    }
+  }
+  return endpoints;
+};
+
+// src/contractCheck.ts
+import { tryCatch } from "@luckystack/core";
+var DEFAULT_REQUEST_TIMEOUT_MS = 5e3;
+var runContractCheck = async (input) => {
+  const { endpoint, baseUrl } = input;
+  const url = `${baseUrl.replace(/\/$/, "")}/${endpoint.fullPath}`;
+  const body = input.inputFor ? input.inputFor(endpoint) : {};
+  const started = Date.now();
+  const requestTimeoutMs = input.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  const controller = new AbortController();
+  const timeoutHandle = setTimeout(() => {
+    controller.abort();
+  }, requestTimeoutMs);
+  const [fetchError, response] = await tryCatch(() => fetch(url, {
+    method: endpoint.method,
+    headers: {
+      "Content-Type": "application/json",
+      //? Browsers attach Origin on state-changing requests; the server's origin
+      //? policy fail-closes POST/PUT/DELETE without one. Send the same-origin
+      //? value so the request reaches the API pipeline (consumers can override).
+      "Origin": new URL(baseUrl).origin,
+      ...input.headers
+    },
+    body: endpoint.method === "GET" ? void 0 : JSON.stringify(body),
+    signal: controller.signal
+  }));
+  clearTimeout(timeoutHandle);
+  if (fetchError || !response) {
+    return {
+      endpoint,
+      status: "fail",
+      reason: fetchError?.message ?? "fetch returned no response",
+      durationMs: Date.now() - started
+    };
+  }
+  const [parseError, parsed] = await tryCatch(
+    async () => await response.json()
+  );
+  const durationMs = Date.now() - started;
+  if (parseError) {
+    return {
+      endpoint,
+      status: "fail",
+      httpStatus: response.status,
+      responseStatus: "unknown",
+      reason: `JSON parse failed: ${parseError.message}`,
+      durationMs
+    };
+  }
+  if (!parsed || parsed.status !== "success" && parsed.status !== "error") {
+    return {
+      endpoint,
+      status: "fail",
+      httpStatus: response.status,
+      responseStatus: "unknown",
+      reason: "Response missing standard `status` envelope",
+      durationMs
+    };
+  }
+  if (parsed.status === "error" && !parsed.errorCode) {
+    return {
+      endpoint,
+      status: "fail",
+      httpStatus: response.status,
+      responseStatus: "error",
+      reason: "Error response missing `errorCode`",
+      durationMs
+    };
+  }
+  return {
+    endpoint,
+    status: "pass",
+    httpStatus: response.status,
+    responseStatus: parsed.status,
+    errorCode: parsed.errorCode,
+    durationMs
+  };
+};
+
+// src/runContractTests.ts
+var shouldSkip = (endpoint, skip) => {
+  if (skip.length === 0) return false;
+  const versioned = `${endpoint.page}/${endpoint.name}/${endpoint.version}`;
+  const versionless = `${endpoint.page}/${endpoint.name}`;
+  return skip.includes(versioned) || skip.includes(versionless);
+};
+var runContractTests = async (input) => {
+  const endpoints = walkEndpoints(input.apiMethodMap);
+  const skip = input.skip ?? [];
+  const results = [];
+  for (const endpoint of endpoints) {
+    if (shouldSkip(endpoint, skip)) {
+      const skipped = {
+        endpoint,
+        status: "skipped",
+        durationMs: 0,
+        reason: "Explicitly skipped"
+      };
+      results.push(skipped);
+      input.onResult?.(skipped);
+      continue;
+    }
+    const result = await runContractCheck({
+      endpoint,
+      baseUrl: input.baseUrl,
+      inputFor: input.inputFor,
+      headers: input.headers
+    });
+    results.push(result);
+    input.onResult?.(result);
+  }
+  return {
+    total: results.length,
+    passed: results.filter((r) => r.status === "pass").length,
+    failed: results.filter((r) => r.status === "fail").length,
+    skipped: results.filter((r) => r.status === "skipped").length,
+    results
+  };
+};
+
+// src/authEnforcementCheck.ts
+import { tryCatch as tryCatch2 } from "@luckystack/core";
+var DEFAULT_REQUEST_TIMEOUT_MS2 = 5e3;
+var EXPECTED_ERROR_CODE = "auth.required";
+var runAuthEnforcementCheck = async (input) => {
+  const { endpoint, baseUrl } = input;
+  const url = `${baseUrl.replace(/\/$/, "")}/${endpoint.fullPath}`;
+  const body = input.inputFor ? input.inputFor(endpoint) : {};
+  const started = Date.now();
+  const requestTimeoutMs = input.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS2;
+  const controller = new AbortController();
+  const timeoutHandle = setTimeout(() => {
+    controller.abort();
+  }, requestTimeoutMs);
+  const [fetchError, response] = await tryCatch2(() => fetch(url, {
+    method: endpoint.method,
+    //? No session cookie, no auth header — deliberately. Origin IS sent so the
+    //? server's origin policy doesn't 403 before the auth check can run.
+    headers: { "Content-Type": "application/json", "Origin": new URL(baseUrl).origin },
+    body: endpoint.method === "GET" ? void 0 : JSON.stringify(body),
+    signal: controller.signal
+  }));
+  clearTimeout(timeoutHandle);
+  if (fetchError || !response) {
+    return {
+      endpoint,
+      status: "fail",
+      reason: fetchError?.message ?? "fetch returned no response",
+      durationMs: Date.now() - started
+    };
+  }
+  const [parseError, parsed] = await tryCatch2(
+    async () => await response.json()
+  );
+  const durationMs = Date.now() - started;
+  if (parseError) {
+    return {
+      endpoint,
+      status: "fail",
+      httpStatus: response.status,
+      responseStatus: "unknown",
+      reason: `JSON parse failed: ${parseError.message}`,
+      durationMs
+    };
+  }
+  if (parsed?.status === "success") {
+    return {
+      endpoint,
+      status: "fail",
+      httpStatus: response.status,
+      responseStatus: "success",
+      reason: `auth.login endpoint returned success without a session`,
+      durationMs
+    };
+  }
+  if (parsed?.status !== "error") {
+    return {
+      endpoint,
+      status: "fail",
+      httpStatus: response.status,
+      responseStatus: "unknown",
+      reason: "Response missing standard `status` envelope",
+      durationMs
+    };
+  }
+  if (parsed.errorCode !== EXPECTED_ERROR_CODE) {
+    return {
+      endpoint,
+      status: "fail",
+      httpStatus: response.status,
+      responseStatus: "error",
+      errorCode: parsed.errorCode,
+      reason: `expected errorCode '${EXPECTED_ERROR_CODE}' but got '${parsed.errorCode ?? "(missing)"}'`,
+      durationMs
+    };
+  }
+  return {
+    endpoint,
+    status: "pass",
+    httpStatus: response.status,
+    responseStatus: "error",
+    errorCode: parsed.errorCode,
+    durationMs
+  };
+};
+
+// src/runAuthEnforcementTests.ts
+var shouldSkip2 = (endpoint, skip) => {
+  if (skip.length === 0) return false;
+  const versioned = `${endpoint.page}/${endpoint.name}/${endpoint.version}`;
+  const versionless = `${endpoint.page}/${endpoint.name}`;
+  return skip.includes(versioned) || skip.includes(versionless);
+};
+var requiresLogin = (apiMetaMap, endpoint) => {
+  const meta = apiMetaMap[endpoint.page]?.[endpoint.name]?.[endpoint.version];
+  return meta?.auth.login ?? false;
+};
+var runAuthEnforcementTests = async (input) => {
+  const endpoints = walkEndpoints(input.apiMethodMap);
+  const skip = input.skip ?? [];
+  const results = [];
+  for (const endpoint of endpoints) {
+    if (!requiresLogin(input.apiMetaMap, endpoint)) {
+      continue;
+    }
+    if (shouldSkip2(endpoint, skip)) {
+      const skipped = {
+        endpoint,
+        status: "skipped",
+        durationMs: 0,
+        reason: "Explicitly skipped"
+      };
+      results.push(skipped);
+      input.onResult?.(skipped);
+      continue;
+    }
+    const result = await runAuthEnforcementCheck({
+      endpoint,
+      baseUrl: input.baseUrl,
+      inputFor: input.inputFor
+    });
+    results.push(result);
+    input.onResult?.(result);
+  }
+  return {
+    total: results.length,
+    passed: results.filter((r) => r.status === "pass").length,
+    failed: results.filter((r) => r.status === "fail").length,
+    skipped: results.filter((r) => r.status === "skipped").length,
+    results
+  };
+};
+
+// src/rateLimitCheck.ts
+import { tryCatch as tryCatch3 } from "@luckystack/core";
+var DEFAULT_REQUEST_TIMEOUT_MS3 = 1e4;
+var EXPECTED_ERROR_CODE2 = "api.rateLimitExceeded";
+var runRateLimitCheck = async (input) => {
+  const { endpoint, baseUrl, rateLimit } = input;
+  const url = `${baseUrl.replace(/\/$/, "")}/${endpoint.fullPath}`;
+  const body = input.inputFor ? input.inputFor(endpoint) : {};
+  const started = Date.now();
+  const requestTimeoutMs = input.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS3;
+  const send = async () => {
+    const controller = new AbortController();
+    const timeoutHandle = setTimeout(() => {
+      controller.abort();
+    }, requestTimeoutMs);
+    const [error, response] = await tryCatch3(() => fetch(url, {
+      method: endpoint.method,
+      headers: {
+        "Content-Type": "application/json",
+        "Origin": new URL(baseUrl).origin,
+        ...input.headers
+      },
+      body: endpoint.method === "GET" ? void 0 : JSON.stringify(body),
+      signal: controller.signal
+    }));
+    clearTimeout(timeoutHandle);
+    if (error || !response) return null;
+    return response;
+  };
+  for (let i = 0; i < rateLimit; i += 1) {
+    await send();
+  }
+  const final = await send();
+  const durationMs = Date.now() - started;
+  if (!final) {
+    return {
+      endpoint,
+      status: "fail",
+      reason: "Final rate-limit probe request failed to return a response",
+      durationMs
+    };
+  }
+  const [, parsed] = await tryCatch3(
+    async () => await final.json()
+  );
+  if (parsed?.status === "error" && parsed.errorCode === EXPECTED_ERROR_CODE2) {
+    return {
+      endpoint,
+      status: "pass",
+      httpStatus: final.status,
+      responseStatus: "error",
+      errorCode: parsed.errorCode,
+      durationMs
+    };
+  }
+  return {
+    endpoint,
+    status: "fail",
+    httpStatus: final.status,
+    responseStatus: parsed?.status ?? "unknown",
+    errorCode: parsed?.errorCode,
+    reason: `expected '${EXPECTED_ERROR_CODE2}' on request ${rateLimit + 1} but got ${parsed?.status ?? "none"}/${parsed?.errorCode ?? "(none)"}`,
+    durationMs
+  };
+};
+
+// src/resetServerState.ts
+import { tryCatch as tryCatch4 } from "@luckystack/core";
+var resetServerState = async ({ baseUrl, token }) => {
+  const url = `${baseUrl.replace(/\/$/, "")}/_test/reset`;
+  const headers = { "Content-Type": "application/json" };
+  if (token) headers["X-Test-Reset-Token"] = token;
+  const [error, response] = await tryCatch4(() => fetch(url, { method: "POST", headers }));
+  if (error || !response) return false;
+  return response.ok;
+};
+
+// src/runRateLimitTests.ts
+var getRateLimit = (apiMetaMap, endpoint) => {
+  const meta = apiMetaMap[endpoint.page]?.[endpoint.name]?.[endpoint.version];
+  if (!meta || meta.rateLimit === false || meta.rateLimit === void 0) return null;
+  return meta.rateLimit;
+};
+var requiresLogin2 = (apiMetaMap, endpoint) => {
+  const meta = apiMetaMap[endpoint.page]?.[endpoint.name]?.[endpoint.version];
+  return meta?.auth.login ?? false;
+};
+var shouldSkip3 = (endpoint, skip) => {
+  if (skip.length === 0) return false;
+  const versioned = `${endpoint.page}/${endpoint.name}/${endpoint.version}`;
+  const versionless = `${endpoint.page}/${endpoint.name}`;
+  return skip.includes(versioned) || skip.includes(versionless);
+};
+var runRateLimitTests = async (input) => {
+  const endpoints = walkEndpoints(input.apiMethodMap);
+  const skip = input.skip ?? [];
+  const maxRateLimit = input.maxRateLimitToTest ?? 50;
+  const isAuthenticatedSweep = Boolean(input.headers?.Cookie);
+  const results = [];
+  for (const endpoint of endpoints) {
+    const rateLimit = getRateLimit(input.apiMetaMap, endpoint);
+    if (rateLimit === null) continue;
+    if (!isAuthenticatedSweep && requiresLogin2(input.apiMetaMap, endpoint)) {
+      const skipped = {
+        endpoint,
+        status: "skipped",
+        durationMs: 0,
+        reason: "login-required route \u2014 set TEST_AUTH_TOKEN to rate-limit-test it (unauthenticated calls hit auth.required before the limiter)"
+      };
+      results.push(skipped);
+      input.onResult?.(skipped);
+      continue;
+    }
+    if (rateLimit > maxRateLimit) {
+      const skipped = {
+        endpoint,
+        status: "skipped",
+        durationMs: 0,
+        reason: `rateLimit ${rateLimit} exceeds maxRateLimitToTest=${maxRateLimit}`
+      };
+      results.push(skipped);
+      input.onResult?.(skipped);
+      continue;
+    }
+    if (shouldSkip3(endpoint, skip)) {
+      const skipped = {
+        endpoint,
+        status: "skipped",
+        durationMs: 0,
+        reason: "Explicitly skipped"
+      };
+      results.push(skipped);
+      input.onResult?.(skipped);
+      continue;
+    }
+    if (input.resetBetweenEndpoints) {
+      await resetServerState({ baseUrl: input.baseUrl, token: input.resetToken });
+    }
+    const result = await runRateLimitCheck({
+      endpoint,
+      baseUrl: input.baseUrl,
+      rateLimit,
+      inputFor: input.inputFor,
+      headers: input.headers
+    });
+    results.push(result);
+    input.onResult?.(result);
+  }
+  return {
+    total: results.length,
+    passed: results.filter((r) => r.status === "pass").length,
+    failed: results.filter((r) => r.status === "fail").length,
+    skipped: results.filter((r) => r.status === "skipped").length,
+    results
+  };
+};
+
+// src/fuzzCheck.ts
+import { tryCatch as tryCatch5 } from "@luckystack/core";
+var DEFAULT_REQUEST_TIMEOUT_MS4 = 5e3;
+var JUNK_PAYLOADS = [
+  null,
+  [],
+  [1, 2, 3],
+  "string-instead-of-object",
+  1234567890,
+  true,
+  { nested: { deeply: { nested: { value: "x".repeat(1e4) } } } },
+  { __proto__: { polluted: true } },
+  { key: null, other: void 0, third: Number.NaN }
+];
+var probe = async (endpoint, baseUrl, body, headers, requestTimeoutMs) => {
+  const url = `${baseUrl.replace(/\/$/, "")}/${endpoint.fullPath}`;
+  const controller = new AbortController();
+  const timeoutHandle = setTimeout(() => {
+    controller.abort();
+  }, requestTimeoutMs);
+  const [fetchError, response] = await tryCatch5(() => fetch(url, {
+    method: endpoint.method,
+    headers: { "Content-Type": "application/json", "Origin": new URL(baseUrl).origin, ...headers },
+    body: endpoint.method === "GET" ? void 0 : JSON.stringify(body),
+    signal: controller.signal
+  }));
+  clearTimeout(timeoutHandle);
+  if (fetchError || !response) return null;
+  const [, parsed] = await tryCatch5(
+    async () => await response.json()
+  );
+  return { httpStatus: response.status, parsed: parsed ?? null };
+};
+var runFuzzCheck = async (input) => {
+  const started = Date.now();
+  const requestTimeoutMs = input.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS4;
+  for (const payload of JUNK_PAYLOADS) {
+    const result = await probe(input.endpoint, input.baseUrl, payload, input.headers, requestTimeoutMs);
+    const durationMs = Date.now() - started;
+    if (!result) {
+      return {
+        endpoint: input.endpoint,
+        status: "fail",
+        reason: `fuzz probe crashed (no response) with payload: ${JSON.stringify(payload).slice(0, 80)}`,
+        durationMs
+      };
+    }
+    if (!result.parsed || result.parsed.status !== "success" && result.parsed.status !== "error") {
+      return {
+        endpoint: input.endpoint,
+        status: "fail",
+        httpStatus: result.httpStatus,
+        reason: `fuzz payload produced non-envelope response: ${JSON.stringify(payload).slice(0, 80)}`,
+        durationMs
+      };
+    }
+    if (result.parsed.status === "error" && typeof result.parsed.errorCode !== "string") {
+      return {
+        endpoint: input.endpoint,
+        status: "fail",
+        httpStatus: result.httpStatus,
+        reason: `fuzz error response missing errorCode for payload: ${JSON.stringify(payload).slice(0, 80)}`,
+        durationMs
+      };
+    }
+  }
+  return {
+    endpoint: input.endpoint,
+    status: "pass",
+    durationMs: Date.now() - started
+  };
+};
+
+// src/runFuzzTests.ts
+var shouldSkip4 = (endpoint, skip) => {
+  if (skip.length === 0) return false;
+  const versioned = `${endpoint.page}/${endpoint.name}/${endpoint.version}`;
+  const versionless = `${endpoint.page}/${endpoint.name}`;
+  return skip.includes(versioned) || skip.includes(versionless);
+};
+var runFuzzTests = async (input) => {
+  const endpoints = walkEndpoints(input.apiMethodMap);
+  const skip = input.skip ?? [];
+  const results = [];
+  for (const endpoint of endpoints) {
+    if (shouldSkip4(endpoint, skip)) {
+      const skipped = {
+        endpoint,
+        status: "skipped",
+        durationMs: 0,
+        reason: "Explicitly skipped"
+      };
+      results.push(skipped);
+      input.onResult?.(skipped);
+      continue;
+    }
+    const result = await runFuzzCheck({
+      endpoint,
+      baseUrl: input.baseUrl,
+      headers: input.headers
+    });
+    results.push(result);
+    input.onResult?.(result);
+  }
+  return {
+    total: results.length,
+    passed: results.filter((r) => r.status === "pass").length,
+    failed: results.filter((r) => r.status === "fail").length,
+    skipped: results.filter((r) => r.status === "skipped").length,
+    results
+  };
+};
+
+// src/schemaSampleInput.ts
+var sampleForDef = (def) => {
+  const d = def;
+  const name = d.typeName ?? d.type;
+  switch (name) {
+    case "ZodString":
+    case "string": {
+      return "test";
+    }
+    case "ZodNumber":
+    case "number": {
+      return 0;
+    }
+    case "ZodBoolean":
+    case "boolean": {
+      return false;
+    }
+    case "ZodNull":
+    case "null": {
+      return null;
+    }
+    case "ZodUndefined":
+    case "undefined": {
+      return void 0;
+    }
+    case "ZodAny":
+    case "any":
+    case "ZodUnknown":
+    case "unknown": {
+      return null;
+    }
+    case "ZodLiteral":
+    case "literal": {
+      return d.value ?? d.values?.[0];
+    }
+    case "ZodOptional":
+    case "optional":
+    case "ZodNullable":
+    case "nullable": {
+      return void 0;
+    }
+    case "ZodUnion":
+    case "union": {
+      return d.options && d.options.length > 0 && d.options[0] ? sampleForDef(d.options[0]._def) : null;
+    }
+    case "ZodArray":
+    case "array": {
+      return [];
+    }
+    case "ZodObject":
+    case "object": {
+      const out = {};
+      const shape = typeof d.shape === "function" ? d.shape() : d.shape ?? {};
+      for (const [key, valueSchema] of Object.entries(shape)) {
+        const sample = sampleForDef(valueSchema._def);
+        if (sample !== void 0) out[key] = sample;
+      }
+      return out;
+    }
+    case "ZodRecord":
+    case "record": {
+      return {};
+    }
+    case "ZodDate":
+    case "date": {
+      return (/* @__PURE__ */ new Date()).toISOString();
+    }
+    default: {
+      return null;
+    }
+  }
+};
+var sampleSchemaInput = (schema) => {
+  return sampleForDef(schema.def);
+};
+
+// src/reporter.ts
+var statusIcon = (status) => {
+  switch (status) {
+    case "pass": {
+      return "[PASS]";
+    }
+    case "fail": {
+      return "[FAIL]";
+    }
+    case "skipped": {
+      return "[SKIP]";
+    }
+  }
+};
+var logContractResult = (result) => {
+  const { endpoint, durationMs, httpStatus, responseStatus, errorCode, reason } = result;
+  const icon = statusIcon(result.status);
+  const core = `${icon} ${endpoint.method} /${endpoint.fullPath} ${durationMs}ms`;
+  if (result.status === "pass") {
+    const tail = responseStatus === "error" ? ` (error: ${errorCode ?? "unknown"})` : "";
+    console.log(`${core} http=${httpStatus ?? "-"}${tail}`);
+    return;
+  }
+  if (result.status === "skipped") {
+    console.log(`${core} ${reason ?? ""}`);
+    return;
+  }
+  console.log(`${core} http=${httpStatus ?? "-"} reason=${reason ?? "(none)"}`);
+};
+var logContractSummary = (summary) => {
+  const { total, passed, failed, skipped } = summary;
+  console.log("");
+  console.log(`Contract tests: ${passed}/${total} passed, ${failed} failed, ${skipped} skipped`);
+  if (failed > 0) {
+    console.log("");
+    console.log("Failures:");
+    for (const result of summary.results) {
+      if (result.status !== "fail") continue;
+      console.log(`  - /${result.endpoint.fullPath}: ${result.reason ?? "(no reason)"}`);
+    }
+  }
+};
+
+// src/customTests.ts
+import fs from "fs";
+import path from "path";
+import { pathToFileURL } from "url";
+import { getCsrfConfig, getPrismaClient, getProjectConfig, getSrcDir, tryCatch as tryCatch7 } from "@luckystack/core";
+
+// src/streamWatcher.ts
+import { io as createSocketIoClient } from "socket.io-client";
+import {
+  buildJoinRoomResponseEventName,
+  socketEventNames,
+  tryCatch as tryCatch6
+} from "@luckystack/core";
+var DEFAULT_TIMEOUT_MS = 5e3;
+var JOIN_RESPONSE_TIMEOUT_MS = 3e3;
+var CONNECT_TIMEOUT_MS = 3e3;
+var isJoinRoomResponse = (value) => typeof value === "object" && value !== null;
+var isStreamChunkFrame = (value) => typeof value === "object" && value !== null;
+var responseIndexCounter = 0;
+var nextResponseIndex = () => {
+  responseIndexCounter += 1;
+  return responseIndexCounter;
+};
+var waitForConnect = (socket) => {
+  return new Promise((resolve, reject) => {
+    if (socket.connected) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(() => {
+      cleanup();
+      reject(new Error(`watchStream: socket failed to connect within ${CONNECT_TIMEOUT_MS}ms`));
+    }, CONNECT_TIMEOUT_MS);
+    const onConnect = () => {
+      cleanup();
+      resolve();
+    };
+    const onConnectError = (err) => {
+      cleanup();
+      reject(new Error(`watchStream: connect_error \u2014 ${err.message}`));
+    };
+    const cleanup = () => {
+      clearTimeout(timer);
+      socket.off("connect", onConnect);
+      socket.off("connect_error", onConnectError);
+    };
+    socket.on("connect", onConnect);
+    socket.on("connect_error", onConnectError);
+  });
+};
+var waitForJoinAck = (socket, responseIndex) => {
+  const eventName = buildJoinRoomResponseEventName(responseIndex);
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      socket.off(eventName, onAck);
+      reject(new Error(`watchStream: joinRoom ack timeout after ${JOIN_RESPONSE_TIMEOUT_MS}ms`));
+    }, JOIN_RESPONSE_TIMEOUT_MS);
+    const onAck = (payload) => {
+      clearTimeout(timer);
+      socket.off(eventName, onAck);
+      if (isJoinRoomResponse(payload) && payload.status === "error") {
+        reject(new Error(`watchStream: joinRoom rejected \u2014 ${payload.errorCode ?? "unknown"}`));
+        return;
+      }
+      resolve();
+    };
+    socket.on(eventName, onAck);
+  });
+};
+var openStreamWatcher = async (input) => {
+  const defaultTimeoutMs = input.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const chunks = [];
+  const waiters = [];
+  const socket = createSocketIoClient(input.baseUrl, {
+    transports: ["websocket"],
+    forceNew: true,
+    reconnection: false,
+    auth: input.token ? { token: input.token } : void 0
+  });
+  const handleChunk = (raw) => {
+    if (!isStreamChunkFrame(raw)) return;
+    if (raw.status !== "stream") return;
+    if (raw.fullName !== input.routeFullName) return;
+    const chunk = raw;
+    chunks.push(chunk);
+    for (let i = waiters.length - 1; i >= 0; i--) {
+      const waiter = waiters[i];
+      if (!waiter) continue;
+      if (waiter.predicate(chunks)) {
+        waiters.splice(i, 1);
+        waiter.resolve();
+      }
+    }
+  };
+  socket.on(socketEventNames.sync, handleChunk);
+  await waitForConnect(socket);
+  const responseIndex = nextResponseIndex();
+  socket.emit(socketEventNames.joinRoom, {
+    group: input.roomCode,
+    responseIndex
+  });
+  const [joinError] = await tryCatch6(() => waitForJoinAck(socket, responseIndex));
+  if (joinError) {
+    socket.off(socketEventNames.sync, handleChunk);
+    socket.disconnect();
+    throw joinError;
+  }
+  let closed = false;
+  const close = () => {
+    if (closed) return Promise.resolve();
+    closed = true;
+    socket.off(socketEventNames.sync, handleChunk);
+    for (const waiter of waiters) waiter.resolve();
+    waiters.length = 0;
+    socket.disconnect();
+    return Promise.resolve();
+  };
+  const stopAt = (predicate, timeoutMs = defaultTimeoutMs) => {
+    if (predicate(chunks)) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const waiter = {
+        predicate,
+        resolve: () => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          resolve();
+        }
+      };
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        const idx = waiters.indexOf(waiter);
+        if (idx !== -1) waiters.splice(idx, 1);
+        reject(new Error(
+          `watchStream.stopAt: predicate not satisfied within ${timeoutMs}ms (received ${chunks.length} chunks)`
+        ));
+      }, timeoutMs);
+      waiters.push(waiter);
+    });
+  };
+  const waitForCount = (n, timeoutMs = defaultTimeoutMs) => {
+    return stopAt((current) => current.length >= n, timeoutMs);
+  };
+  return {
+    chunks,
+    stopAt,
+    waitForCount,
+    close
+  };
+};
+
+// src/customTests.ts
+var API_TEST_FILE_PATTERN = /_v(\d+)\.tests\.ts$/;
+var SYNC_SERVER_TEST_FILE_PATTERN = /_server_v(\d+)\.tests\.ts$/;
+var discoverCustomTestFiles = (srcDir = getSrcDir()) => {
+  if (!fs.existsSync(srcDir)) return [];
+  const found = [];
+  const stack = [srcDir];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (current === void 0) break;
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+        continue;
+      }
+      if (!entry.isFile() || !entry.name.endsWith(".tests.ts")) continue;
+      const parentDir = path.basename(current);
+      if (parentDir !== "_api" && parentDir !== "_sync") continue;
+      const pattern = parentDir === "_api" ? API_TEST_FILE_PATTERN : SYNC_SERVER_TEST_FILE_PATTERN;
+      const versionMatch = pattern.exec(entry.name);
+      if (!versionMatch) continue;
+      const version = `v${versionMatch[1]}`;
+      const namePart = entry.name.replace(parentDir === "_api" ? /_v\d+\.tests\.ts$/ : /_server_v\d+\.tests\.ts$/, "");
+      const pageDir = path.dirname(current);
+      const relativePage = path.relative(srcDir, pageDir).replaceAll("\\", "/") || "system";
+      found.push({
+        filePath: fullPath,
+        kind: parentDir === "_api" ? "api" : "sync",
+        route: { page: relativePage, name: namePart, version }
+      });
+    }
+  }
+  return found.toSorted((a, b) => a.filePath.localeCompare(b.filePath));
+};
+var AssertionError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AssertionError";
+  }
+};
+var buildExpect = () => ({
+  eq: (actual, expected, message) => {
+    const ok = Object.is(actual, expected) || typeof actual === "object" && typeof expected === "object" && JSON.stringify(actual) === JSON.stringify(expected);
+    if (!ok) {
+      const prefix = message ? `${message}: ` : "";
+      throw new AssertionError(`${prefix}expected ${JSON.stringify(expected)} but got ${JSON.stringify(actual)}`);
+    }
+  },
+  ok: (value, message) => {
+    if (!value) throw new AssertionError(message ?? `expected truthy value, got ${JSON.stringify(value)}`);
+  },
+  throws: async (fn, message) => {
+    const [err] = await tryCatch7(fn);
+    if (!err) throw new AssertionError(message ?? "expected fn to throw, but it did not");
+    return err;
+  },
+  matches: (value, pattern, message) => {
+    if (!pattern.test(value)) {
+      const prefix = message ? `${message}: ` : "";
+      throw new AssertionError(`${prefix}"${value}" does not match ${pattern}`);
+    }
+  }
+});
+var extractErrorCode = (response) => {
+  if (!response || typeof response !== "object") return void 0;
+  const r = response;
+  if (typeof r.errorCode === "string" && r.errorCode.length > 0) return r.errorCode;
+  if (typeof r.status === "string" && r.status !== "success") return r.status;
+  return void 0;
+};
+var buildSessionHelpers = (state) => {
+  return {
+    login: async (user) => {
+      const { saveSession, getSession } = await import("@luckystack/login");
+      const userId = user?.id ?? `test-user-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+      const email = user?.email ?? `test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
+      const name = user?.name ?? "Test User";
+      const token = `test-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+      const sessionData = {
+        id: userId,
+        email,
+        name,
+        token,
+        provider: "credentials"
+      };
+      await saveSession(token, sessionData, true);
+      state.token = token;
+      state.userId = userId;
+      const persisted = await getSession(token);
+      state.csrfToken = persisted?.csrfToken ?? null;
+      return { token, userId };
+    },
+    logout: async () => {
+      if (!state.token) return;
+      const { deleteSession } = await import("@luckystack/login");
+      await deleteSession(state.token);
+      state.token = null;
+      state.userId = null;
+      state.csrfToken = null;
+    },
+    current: () => ({ token: state.token, userId: state.userId })
+  };
+};
+var buildCallApi = (baseUrl, routePath, state, cookieName, method) => {
+  return async (input) => {
+    const url = `${baseUrl.replace(/\/$/, "")}/api/${routePath}`;
+    const headers = { "Content-Type": "application/json", Origin: new URL(baseUrl).origin };
+    if (state.token) headers.Cookie = `${cookieName}=${state.token}`;
+    if (state.csrfToken) headers[getCsrfConfig().headerName] = state.csrfToken;
+    const init = { method, headers };
+    if (method !== "GET" && method !== "HEAD") init.body = JSON.stringify(input ?? {});
+    const response = await fetch(url, init);
+    const json = await response.json();
+    state.lastResponse = json;
+    return json;
+  };
+};
+var buildCallSync = (baseUrl, routePath, state, cookieName) => {
+  return async (input, opts) => {
+    const url = `${baseUrl.replace(/\/$/, "")}/sync/${routePath}`;
+    const headers = { "Content-Type": "application/json", Origin: new URL(baseUrl).origin };
+    if (state.token) headers.Cookie = `${cookieName}=${state.token}`;
+    if (state.csrfToken) headers[getCsrfConfig().headerName] = state.csrfToken;
+    const body = { data: input ?? {}, receiver: opts?.receiver };
+    const response = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body)
+    });
+    const json = await response.json();
+    state.lastResponse = json;
+    return json;
+  };
+};
+var buildContext = (discovery, input) => {
+  const cookieName = input.sessionCookieName ?? getProjectConfig().http.sessionCookieName;
+  const routePath = `${discovery.route.page}/${discovery.route.name}/${discovery.route.version}`;
+  const routeFullName = `sync/${routePath}`;
+  const apiMethod = input.apiMethodMap?.[discovery.route.page]?.[discovery.route.name]?.[discovery.route.version] ?? "POST";
+  const state = { token: null, userId: null, csrfToken: null, lastResponse: null };
+  const prisma = getPrismaClient();
+  const watchers = [];
+  const watchStream = async (roomCode) => {
+    const watcher = await openStreamWatcher({
+      baseUrl: input.baseUrl,
+      roomCode,
+      token: state.token,
+      routeFullName
+    });
+    watchers.push(watcher);
+    return watcher;
+  };
+  const closeAllWatchers = async () => {
+    while (watchers.length > 0) {
+      const watcher = watchers.pop();
+      if (!watcher) continue;
+      const [closeError] = await tryCatch7(() => watcher.close());
+      if (closeError) {
+      }
+    }
+  };
+  const ctx = {
+    callApi: buildCallApi(input.baseUrl, routePath, state, cookieName, apiMethod),
+    callSync: buildCallSync(input.baseUrl, routePath, state, cookieName),
+    watchStream,
+    session: buildSessionHelpers(state),
+    prisma,
+    expect: buildExpect()
+  };
+  return { ctx, closeAllWatchers, state };
+};
+var runCustomTests = async (input) => {
+  const files = discoverCustomTestFiles();
+  const results = [];
+  for (const discovery of files) {
+    const routePath = `${discovery.route.page}/${discovery.route.name}/${discovery.route.version}`;
+    if (input.filter && !routePath.includes(input.filter)) continue;
+    const [importError, mod] = await tryCatch7(
+      () => import(pathToFileURL(discovery.filePath).href)
+    );
+    if (importError || !mod) {
+      const r = {
+        routePath,
+        caseName: "(import)",
+        status: "fail",
+        durationMs: 0,
+        reason: `failed to import ${discovery.filePath}: ${importError?.message ?? "unknown"}`
+      };
+      results.push(r);
+      input.onResult?.(r);
+      continue;
+    }
+    const exported = mod.customTests;
+    if (!Array.isArray(exported) || exported.length === 0) {
+      continue;
+    }
+    for (const rawCase of exported) {
+      const c = rawCase;
+      if (typeof c.name !== "string" || typeof c.run !== "function") continue;
+      const expectedToFail = typeof c.expectedToFail === "string" ? c.expectedToFail : void 0;
+      const built = buildContext(discovery, input);
+      const started = Date.now();
+      const [runError] = await tryCatch7(async () => c.run(built.ctx));
+      await tryCatch7(() => built.closeAllWatchers());
+      const durationMs = Date.now() - started;
+      let r;
+      if (runError) {
+        const errorCode = extractErrorCode(built.state.lastResponse);
+        const reason = errorCode ? `${runError.message} (server: ${errorCode})` : runError.message;
+        r = expectedToFail ? { routePath, caseName: c.name, status: "xfail", durationMs, reason, expectedToFail } : { routePath, caseName: c.name, status: "fail", durationMs, reason };
+      } else {
+        r = expectedToFail ? {
+          routePath,
+          caseName: c.name,
+          status: "xpass",
+          durationMs,
+          reason: `marked expectedToFail ("${expectedToFail}") but passed \u2014 remove the marker`,
+          expectedToFail
+        } : { routePath, caseName: c.name, status: "pass", durationMs };
+      }
+      results.push(r);
+      input.onResult?.(r);
+    }
+  }
+  return {
+    total: results.length,
+    passed: results.filter((r) => r.status === "pass").length,
+    failed: results.filter((r) => r.status === "fail").length,
+    xfailed: results.filter((r) => r.status === "xfail").length,
+    xpassed: results.filter((r) => r.status === "xpass").length,
+    results
+  };
+};
+
+// src/runAllTests.ts
+import { clearAllRateLimits, getProjectConfig as getProjectConfig2 } from "@luckystack/core";
+var inputForEndpoint = (apiInputSchemas) => (endpoint) => {
+  const schema = apiInputSchemas[endpoint.page]?.[endpoint.name]?.[endpoint.version];
+  return schema ? sampleSchemaInput(schema) : {};
+};
+var matchesFilter = (endpoint, filter) => {
+  if (!filter) return true;
+  return `${endpoint.page}/${endpoint.name}/${endpoint.version}`.includes(filter);
+};
+var filterResults = (results, filter) => filter ? results.filter((r) => matchesFilter(r.endpoint, filter)) : results;
+var cloneSummary = (summary, filter) => {
+  if (!filter) return summary;
+  const results = filterResults(summary.results, filter);
+  return {
+    total: results.length,
+    passed: results.filter((r) => r.status === "pass").length,
+    failed: results.filter((r) => r.status === "fail").length,
+    skipped: results.filter((r) => r.status === "skipped").length,
+    results
+  };
+};
+var runAllTests = async (input) => {
+  const summary = { totalPassed: 0, totalFailed: 0 };
+  const headers = {};
+  if (input.authToken) {
+    const cookieName = input.sessionCookieName ?? getProjectConfig2().http.sessionCookieName;
+    headers.Cookie = `${cookieName}=${input.authToken}`;
+  }
+  const inputFor = inputForEndpoint(input.apiInputSchemas);
+  if (!input.noSweep) {
+    const contract = await runContractTests({
+      apiMethodMap: input.apiMethodMap,
+      baseUrl: input.baseUrl,
+      skip: input.skip,
+      headers,
+      inputFor
+    });
+    summary.contract = cloneSummary(contract, input.filter);
+    const auth = await runAuthEnforcementTests({
+      apiMethodMap: input.apiMethodMap,
+      apiMetaMap: input.apiMetaMap,
+      baseUrl: input.baseUrl,
+      skip: input.skip,
+      inputFor
+    });
+    summary.auth = cloneSummary(auth, input.filter);
+    if (!input.noRateLimit) {
+      const rateLimit = await runRateLimitTests({
+        apiMethodMap: input.apiMethodMap,
+        apiMetaMap: input.apiMetaMap,
+        baseUrl: input.baseUrl,
+        skip: input.skip,
+        headers,
+        inputFor
+      });
+      summary.rateLimit = cloneSummary(rateLimit, input.filter);
+    }
+    if (!input.noFuzz) {
+      const fuzz = await runFuzzTests({
+        apiMethodMap: input.apiMethodMap,
+        baseUrl: input.baseUrl,
+        skip: input.skip,
+        headers
+      });
+      summary.fuzz = cloneSummary(fuzz, input.filter);
+    }
+  }
+  if (!input.noCustom) {
+    try {
+      await clearAllRateLimits();
+    } catch {
+    }
+    const custom = await runCustomTests({
+      baseUrl: input.baseUrl,
+      sessionCookieName: input.sessionCookieName,
+      filter: input.filter,
+      //? Pass the generated method map so the harness invokes each API route
+      //? with its declared HTTP method (e.g. logout is DELETE, not POST).
+      apiMethodMap: input.apiMethodMap
+    });
+    summary.custom = custom;
+  }
+  summary.totalPassed = (summary.contract?.passed ?? 0) + (summary.auth?.passed ?? 0) + (summary.rateLimit?.passed ?? 0) + (summary.fuzz?.passed ?? 0) + (summary.custom?.passed ?? 0);
+  summary.totalFailed = (summary.contract?.failed ?? 0) + (summary.auth?.failed ?? 0) + (summary.rateLimit?.failed ?? 0) + (summary.fuzz?.failed ?? 0) + (summary.custom?.failed ?? 0);
+  return summary;
+};
+var useColor = (() => {
+  if (process.env.NO_COLOR) return false;
+  if (process.env.FORCE_COLOR) return true;
+  return process.stdout.isTTY;
+})();
+var paint = (code, text) => useColor ? `\x1B[${code}m${text}\x1B[0m` : text;
+var green = (t) => paint("32", t);
+var red = (t) => paint("31", t);
+var yellow = (t) => paint("33", t);
+var dim = (t) => paint("2", t);
+var bold = (t) => paint("1", t);
+var xfailOf = (s) => s && "xfailed" in s ? s.xfailed : 0;
+var skippedOf = (s) => s && "skipped" in s ? s.skipped : 0;
+var formatLayerLine = (label, s) => {
+  if (!s) return `  ${dim("\u2013")} ${label.padEnd(18)} ${dim("(layer skipped)")}`;
+  const clean = s.failed === 0;
+  const mark = clean ? green("\u2713") : red("\u2717");
+  const head = clean ? green(`${s.passed}/${s.total} passed`) : `${green(`${s.passed}/${s.total} passed`)}  ${red(`${s.failed}/${s.total} failed`)}`;
+  const extras = [];
+  const xf = xfailOf(s);
+  const sk = skippedOf(s);
+  if (xf) extras.push(yellow(`${xf} expected-fail`));
+  if (sk) extras.push(dim(`${sk} skipped`));
+  const extra = extras.length > 0 ? `  ${dim("\xB7")} ${extras.join(dim(", "))}` : "";
+  return `  ${mark} ${label.padEnd(18)} ${head}${extra}`;
+};
+var sweepFailRows = (s) => (s?.results ?? []).filter((r) => r.status === "fail").map((r) => ({
+  label: `${r.endpoint.page}/${r.endpoint.name}/${r.endpoint.version}`,
+  reason: r.errorCode ? `${r.reason ?? "failed"} [${r.errorCode}]` : r.reason
+}));
+var sweepSkipRows = (layer, s) => (s?.results ?? []).filter((r) => r.status === "skipped").map((r) => ({
+  label: `${layer}: ${r.endpoint.page}/${r.endpoint.name}/${r.endpoint.version}`,
+  reason: r.reason
+}));
+var customRows = (s, status) => (s?.results ?? []).filter((r) => r.status === status).map((r) => ({ label: `${r.routePath} :: ${r.caseName}`, reason: r.reason }));
+var printSection = (title, heading, rows, bullet) => {
+  if (rows.length === 0) return;
+  console.log("");
+  console.log(title(bold(`${heading} (${rows.length})`)));
+  for (const row of rows) {
+    console.log(`  ${title(bullet)} ${row.label}`);
+    if (row.reason) console.log(`      ${dim(row.reason)}`);
+  }
+};
+var logRunAllSummary = (summary) => {
+  console.log("");
+  console.log(formatLayerLine("contract", summary.contract));
+  console.log(formatLayerLine("auth-enforcement", summary.auth));
+  console.log(formatLayerLine("rate-limit", summary.rateLimit));
+  console.log(formatLayerLine("fuzz", summary.fuzz));
+  console.log(formatLayerLine("custom", summary.custom));
+  const failed = [
+    ...sweepFailRows(summary.contract),
+    ...sweepFailRows(summary.auth),
+    ...sweepFailRows(summary.rateLimit),
+    ...sweepFailRows(summary.fuzz),
+    ...customRows(summary.custom, "fail")
+  ];
+  printSection(red, "Failed \u2014 must be fixed (real bugs / wrong tests)", failed, "\u2717");
+  printSection(yellow, "Expected failures \u2014 known issues, allowed to fail", customRows(summary.custom, "xfail"), "\u26A0");
+  printSection(yellow, "Unexpectedly passed \u2014 remove the expectedToFail marker", customRows(summary.custom, "xpass"), "?");
+  const skipped = [
+    ...sweepSkipRows("contract", summary.contract),
+    ...sweepSkipRows("auth", summary.auth),
+    ...sweepSkipRows("rate-limit", summary.rateLimit),
+    ...sweepSkipRows("fuzz", summary.fuzz)
+  ];
+  printSection(dim, "Skipped \u2014 not run (with reason)", skipped, "\u2013");
+  const totalXfail = xfailOf(summary.contract) + xfailOf(summary.auth) + xfailOf(summary.rateLimit) + xfailOf(summary.fuzz) + xfailOf(summary.custom);
+  const totalSkipped = skippedOf(summary.contract) + skippedOf(summary.auth) + skippedOf(summary.rateLimit) + skippedOf(summary.fuzz) + skippedOf(summary.custom);
+  console.log("");
+  const parts = [
+    green(`${summary.totalPassed} passed`),
+    summary.totalFailed > 0 ? red(`${summary.totalFailed} failed`) : dim("0 failed"),
+    totalXfail > 0 ? yellow(`${totalXfail} expected-fail`) : dim("0 expected-fail"),
+    totalSkipped > 0 ? yellow(`${totalSkipped} skipped`) : dim("0 skipped")
+  ];
+  console.log(`Summary: ${parts.join(dim("  \xB7  "))}`);
+  console.log(dim("  legend: \u2717 red = must fix \xB7 \u26A0 yellow = known/allowed \xB7 \u2013 skipped (not run)"));
+};
+
+// src/extensionRegistry.ts
+var layers = /* @__PURE__ */ new Map();
+var fixtures = /* @__PURE__ */ new Map();
+var reporter = null;
+var registerTestLayer = (layer) => {
+  layers.set(layer.name, layer);
+};
+var listTestLayers = () => [...layers.values()];
+var registerTestFixture = (typeKey, fixture) => {
+  fixtures.set(typeKey, fixture);
+};
+var getTestFixture = (typeKey) => fixtures.get(typeKey);
+var registerTestReporter = (newReporter) => {
+  reporter = newReporter;
+};
+var getTestReporter = () => reporter;
+var resetTestExtensionsForTests = () => {
+  layers.clear();
+  fixtures.clear();
+  reporter = null;
+};
+export {
+  discoverCustomTestFiles,
+  getTestFixture,
+  getTestReporter,
+  listTestLayers,
+  logContractResult,
+  logContractSummary,
+  logRunAllSummary,
+  openStreamWatcher,
+  registerTestFixture,
+  registerTestLayer,
+  registerTestReporter,
+  resetServerState,
+  resetTestExtensionsForTests,
+  runAllTests,
+  runAuthEnforcementCheck,
+  runAuthEnforcementTests,
+  runContractCheck,
+  runContractTests,
+  runCustomTests,
+  runFuzzCheck,
+  runFuzzTests,
+  runRateLimitCheck,
+  runRateLimitTests,
+  sampleSchemaInput,
+  walkEndpoints
+};
+//# sourceMappingURL=index.js.map