@elench/testkit 0.1.25 → 0.1.27

package/lib/setup/index.d.ts

@@ -0,0 +1,104 @@
+import type { AuthAdapter, HeaderBuilder, HttpSuiteConfig } from "../index";
+
+export interface LocalDatabaseConfig {
+  provider: "local";
+  image?: string;
+  password?: string;
+  reset?: boolean;
+  template?: {
+    inputs?: string[];
+  };
+  user?: string;
+}
+
+export interface LifecycleConfig {
+  cmd: string;
+  cwd?: string;
+  testkitCmd?: string;
+  testkitCwd?: string;
+}
+
+export interface ServiceConfig {
+  database?: LocalDatabaseConfig;
+  databaseFrom?: string;
+  dependsOn?: string[];
+  discovery?: {
+    roots?: string[];
+  };
+  envFile?: string;
+  envFiles?: string[];
+  local?: {
+    baseUrl: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    port?: number;
+    readyTimeoutMs?: number;
+    readyUrl: string;
+    start: string;
+  };
+  migrate?: LifecycleConfig;
+  seed?: LifecycleConfig;
+}
+
+export interface TestkitSetup {
+  profiles?: {
+    http?: Record<string, HttpSuiteConfig>;
+  };
+  services?: Record<string, ServiceConfig>;
+  telemetry?: {
+    enabled?: boolean;
+    endpoint?: string;
+    timeoutMs?: number;
+    tokenEnv?: string;
+  };
+}
+
+export declare function defineTestkitSetup<T extends TestkitSetup>(setup: T): T;
+export declare function defineHttpProfile<T extends HttpSuiteConfig>(profile: T): T;
+export declare function service<T extends ServiceConfig>(config: T): T;
+export declare function localDatabase(options?: Omit<LocalDatabaseConfig, "provider">): LocalDatabaseConfig;
+export declare function lifecycle(cmd: string, options?: Omit<LifecycleConfig, "cmd">): LifecycleConfig;
+export declare function goService(options: ServiceConfig["local"] & {
+  command?: string;
+  entrypoint?: string;
+  envFiles?: string[];
+  readyPath?: string;
+}): ServiceConfig;
+export declare function nextService(options: ServiceConfig["local"] & {
+  envFiles?: string[];
+}): ServiceConfig;
+export declare function tsxService(options: ServiceConfig["local"] & {
+  entry?: string;
+  envFiles?: string[];
+  readyPath?: string;
+}): ServiceConfig;
+export declare function clerkSessionProfile(options?: {
+  apiBase?: string;
+  needsAuth?: boolean;
+  secretKeyEnv?: string;
+}): HttpSuiteConfig;
+export declare function jsonSessionProfile(options?: {
+  body?: (context: { env: Record<string, string> }) => unknown;
+  cookieName?: string;
+  headers?: Record<string, string>;
+  loginPath?: string;
+  passwordEnv?: string;
+  successStatus?: number;
+  usernameEnv?: string;
+}): HttpSuiteConfig;
+
+export declare function registerRepoSetup(setup: unknown): void;
+export declare function getRepoSetup(): unknown;
+export declare function clearRepoSetup(): void;
+export declare function registerRuntimeContext(context: unknown): void;
+export declare function getRuntimeContext(): unknown;
+export declare function clearRuntimeContext(): void;
+export declare const runtimeHttp: {
+  del(url: string, body?: unknown, params?: unknown): unknown;
+  file(data: unknown, filename?: string, contentType?: string): unknown;
+  get(url: string, params?: unknown): unknown;
+  patch(url: string, body?: unknown, params?: unknown): unknown;
+  post(url: string, body?: unknown, params?: unknown): unknown;
+  put(url: string, body?: unknown, params?: unknown): unknown;
+};
+export declare function runtimeJson<T = unknown>(response: { body: string }): T;

package/lib/setup/index.mjs

@@ -0,0 +1,292 @@
+import {
+  clearRepoSetup,
+  clearRuntimeContext,
+  getRepoSetup,
+  getRuntimeContext,
+  getRuntimeEnv,
+  registerRepoSetup,
+  registerRuntimeContext,
+  runtimeHttp,
+  runtimeJson,
+} from "./runtime.mjs";
+
+export function defineTestkitSetup(setup) {
+  return setup || {};
+}
+
+export function defineHttpProfile(profile) {
+  return profile || {};
+}
+
+export function service(config) {
+  return config || {};
+}
+
+export function localDatabase(options = {}) {
+  return {
+    provider: "local",
+    ...options,
+  };
+}
+
+export function lifecycle(cmd, options = {}) {
+  return {
+    cmd,
+    cwd: options.cwd,
+    testkitCmd: options.testkitCmd,
+    testkitCwd: options.testkitCwd,
+  };
+}
+
+export function goService(options = {}) {
+  const cwd = options.cwd || ".";
+  const port = requiredNumber(options.port, "goService port");
+  const readyPath = options.readyPath || "/health";
+  const baseUrl = options.baseUrl || "http://127.0.0.1:{port}";
+
+  return {
+    ...service(options),
+    local: {
+      cwd,
+      start: options.start || defaultGoStartCommand(options),
+      port,
+      baseUrl,
+      readyUrl: options.readyUrl || `${baseUrl}${readyPath}`,
+      readyTimeoutMs: options.readyTimeoutMs,
+      env: options.env || {},
+    },
+  };
+}
+
+export function nextService(options = {}) {
+  const cwd = options.cwd || ".";
+  const port = requiredNumber(options.port, "nextService port");
+  const baseUrl = options.baseUrl || "http://127.0.0.1:{port}";
+
+  return {
+    ...service(options),
+    local: {
+      cwd,
+      start: options.start || "exec ./node_modules/.bin/next dev -p {port}",
+      port,
+      baseUrl,
+      readyUrl: options.readyUrl || baseUrl,
+      readyTimeoutMs: options.readyTimeoutMs,
+      env: options.env || {},
+    },
+  };
+}
+
+export function tsxService(options = {}) {
+  const cwd = options.cwd || ".";
+  const port = requiredNumber(options.port, "tsxService port");
+  const baseUrl = options.baseUrl || "http://127.0.0.1:{port}";
+  const entry = options.entry || "src/index.ts";
+
+  return {
+    ...service(options),
+    local: {
+      cwd,
+      start: options.start || `exec ./node_modules/.bin/tsx watch ${entry}`,
+      port,
+      baseUrl,
+      readyUrl: options.readyUrl || `${baseUrl}${options.readyPath || "/health"}`,
+      readyTimeoutMs: options.readyTimeoutMs,
+      env: options.env || {},
+    },
+  };
+}
+
+export function clerkSessionProfile(options = {}) {
+  const apiBase = options.apiBase || "https://api.clerk.com/v1";
+  const secretKeyEnv = options.secretKeyEnv || "CLERK_SECRET_KEY";
+  const needsAuth = options.needsAuth !== false;
+
+  return defineHttpProfile({
+    auth: {
+      setup() {
+        return resolveClerkSession({
+          apiBase,
+          secretKey: envValue(secretKeyEnv),
+          needsAuth,
+        });
+      },
+      headers(setupData) {
+        return getClerkAuthHeaders(setupData, { apiBase });
+      },
+    },
+  });
+}
+
+export function jsonSessionProfile(options = {}) {
+  const loginPath = options.loginPath || "/api/auth/login";
+  const cookieName = options.cookieName || "session";
+  const body =
+    typeof options.body === "function"
+      ? options.body
+      : () => ({
+          username: envValue(options.usernameEnv || "TESTKIT_USERNAME"),
+          password: envValue(options.passwordEnv || "TESTKIT_PASSWORD"),
+        });
+
+  return defineHttpProfile({
+    auth: {
+      setup({ env }) {
+        const requestBody = body({ env });
+        const res = runtimeHttp.post(`${env.BASE}${loginPath}`, JSON.stringify(requestBody), {
+          headers: {
+            "Content-Type": "application/json",
+            ...(env.routeParams || {}),
+            ...(options.headers || {}),
+          },
+        });
+
+        if (res.status !== (options.successStatus || 200)) {
+          throw new Error(`Login failed (${res.status}): ${res.body}`);
+        }
+
+        const cookie = res.cookies?.[cookieName]?.[0]?.value ?? null;
+        if (!cookie) {
+          throw new Error(`No ${cookieName} cookie returned from login`);
+        }
+
+        return {
+          cookie,
+          body: safeJson(res),
+        };
+      },
+      headers(session) {
+        if (!session?.cookie) return {};
+        return {
+          Cookie: `${cookieName}=${session.cookie}`,
+        };
+      },
+    },
+  });
+}
+
+export {
+  clearRepoSetup,
+  clearRuntimeContext,
+  getRepoSetup,
+  getRuntimeContext,
+  registerRepoSetup,
+  registerRuntimeContext,
+  runtimeHttp,
+  runtimeJson,
+};
+
+function defaultGoStartCommand(options) {
+  if (options.command) {
+    return `exec go run ${options.command}`;
+  }
+  if (options.entrypoint) {
+    return `exec go run ${options.entrypoint}`;
+  }
+  return "exec go run ./cmd/server";
+}
+
+function requiredNumber(value, label) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${label} must be a positive integer`);
+  }
+  return value;
+}
+
+function envValue(name) {
+  const env = getRuntimeEnv();
+  const value = env?.rawEnv?.[name] || env?.[name];
+  if (!value) {
+    throw new Error(`Missing required env var "${name}" for testkit setup`);
+  }
+  return value;
+}
+
+function safeJson(response) {
+  try {
+    return runtimeJson(response);
+  } catch {
+    return null;
+  }
+}
+
+function resolveClerkSession({ apiBase, secretKey, needsAuth }) {
+  if (!needsAuth) {
+    return { jwt: null };
+  }
+
+  const headers = { Authorization: `Bearer ${secretKey}` };
+  const usersRes = runtimeHttp.get(`${apiBase}/users?limit=1&order_by=-created_at`, {
+    headers,
+  });
+  if (usersRes.status !== 200) {
+    throw new Error(`Clerk list users failed (${usersRes.status}): ${usersRes.body}`);
+  }
+
+  const users = runtimeJson(usersRes);
+  if (!users.length) {
+    throw new Error("No Clerk users found for testkit Clerk auth profile");
+  }
+
+  const userId = users[0].id;
+  const sessionsRes = runtimeHttp.get(
+    `${apiBase}/sessions?user_id=${userId}&status=active&limit=1`,
+    { headers }
+  );
+  if (sessionsRes.status !== 200) {
+    throw new Error(`Clerk list sessions failed (${sessionsRes.status}): ${sessionsRes.body}`);
+  }
+
+  const sessions = runtimeJson(sessionsRes);
+  if (!sessions?.length) {
+    throw new Error("No active Clerk session found for testkit Clerk auth profile");
+  }
+
+  const sessionId = sessions[0].id;
+  const tokenRes = runtimeHttp.post(`${apiBase}/sessions/${sessionId}/tokens`, null, {
+    headers: {
+      ...headers,
+      "Content-Type": "application/json",
+    },
+  });
+  if (tokenRes.status !== 200) {
+    throw new Error(`Clerk create token failed (${tokenRes.status}): ${tokenRes.body}`);
+  }
+
+  return {
+    jwt: runtimeJson(tokenRes).jwt,
+    sessionId,
+    secretKey,
+  };
+}
+
+function getClerkAuthHeaders(setupData, { apiBase }) {
+  if (!setupData?.jwt) return {};
+
+  if (!setupData.sessionId || !setupData.secretKey) {
+    return {
+      Authorization: `Bearer ${setupData.jwt}`,
+      "Content-Type": "application/json",
+    };
+  }
+
+  const tokenRes = runtimeHttp.post(`${apiBase}/sessions/${setupData.sessionId}/tokens`, null, {
+    headers: {
+      Authorization: `Bearer ${setupData.secretKey}`,
+      "Content-Type": "application/json",
+    },
+  });
+  if (tokenRes.status !== 200) {
+    return {
+      Authorization: `Bearer ${setupData.jwt}`,
+      "Content-Type": "application/json",
+    };
+  }
+
+  const nextJwt = runtimeJson(tokenRes).jwt;
+  setupData.jwt = nextJwt;
+  return {
+    Authorization: `Bearer ${nextJwt}`,
+    "Content-Type": "application/json",
+  };
+}

package/lib/setup/runtime.mjs

@@ -0,0 +1,79 @@
+let activeSetup = null;
+let activeRuntimeContext = null;
+
+export function registerRepoSetup(setup) {
+  activeSetup = setup || null;
+}
+
+export function getRepoSetup() {
+  return activeSetup;
+}
+
+export function clearRepoSetup() {
+  activeSetup = null;
+}
+
+export function registerRuntimeContext(context) {
+  activeRuntimeContext = context || null;
+}
+
+export function getRuntimeContext() {
+  return activeRuntimeContext;
+}
+
+export function clearRuntimeContext() {
+  activeRuntimeContext = null;
+}
+
+export function getRuntimeHttp() {
+  const context = getRuntimeContext();
+  if (!context?.http) {
+    throw new Error("Testkit runtime HTTP client is not available in this context");
+  }
+  return context.http;
+}
+
+export function getRuntimeEnv() {
+  const context = getRuntimeContext();
+  if (!context?.env) {
+    throw new Error("Testkit runtime env is not available in this context");
+  }
+  return context.env;
+}
+
+export function runtimeJson(response) {
+  return JSON.parse(response.body);
+}
+
+export function resolveHttpProfile(name) {
+  if (!name) return null;
+
+  const setup = getRepoSetup();
+  if (!setup) return null;
+  const profile = setup?.profiles?.http?.[name];
+  if (!profile) {
+    throw new Error(`Unknown testkit HTTP profile "${name}"`);
+  }
+  return profile;
+}
+
+export const runtimeHttp = {
+  del(url, body, params) {
+    return getRuntimeHttp().del(url, body, params);
+  },
+  file(data, filename, contentType) {
+    return getRuntimeHttp().file(data, filename, contentType);
+  },
+  get(url, params) {
+    return getRuntimeHttp().get(url, params);
+  },
+  patch(url, body, params) {
+    return getRuntimeHttp().patch(url, body, params);
+  },
+  post(url, body, params) {
+    return getRuntimeHttp().post(url, body, params);
+  },
+  put(url, body, params) {
+    return getRuntimeHttp().put(url, body, params);
+  },
+};

package/package.json

@@ -1,11 +1,22 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "CLI for discovering and running local HTTP, DAL, and Playwright test suites",
   "type": "module",
+  "types": "./lib/index.d.ts",
   "exports": {
-    ".": "./lib/index.mjs",
-    "./runtime": "./lib/runtime/index.mjs",
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.mjs"
+    },
+    "./setup": {
+      "types": "./lib/setup/index.d.ts",
+      "default": "./lib/setup/index.mjs"
+    },
+    "./runtime": {
+      "types": "./lib/runtime/index.d.ts",
+      "default": "./lib/runtime/index.mjs"
+    },
     "./package.json": "./package.json"
   },
   "bin": {