@mamund/tram 0.0.0-stage → 0.1.0

package/bin/tram

@@ -0,0 +1,1117 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * tram.js v0.1
+ *
+ * Dependency-free HTTP API test runner.
+ *
+ * Usage:
+ *   tram api-tests.json --validate
+ *   tram api-tests.json
+ *   tram api-tests.json --verbose
+ *   tram api-tests.json --report results.json
+ *   tram api-tests.json --transcript transcript.http
+ *
+ * Requires:
+ *   Node.js 18+
+ *   ./assertions.js
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { evaluateExpectations } = require('../lib/assertions');
+
+const SUPPORTED_MANIFEST_VERSIONS = ['0.1', '0.2'];
+const CURRENT_MANIFEST_VERSION = '0.2';
+
+async function main() {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    const manifestPath = validateManifestPath(args.manifestPath);
+
+    validateOutputPath(args.reportPath, 'Report');
+    validateOutputPath(args.transcriptPath, 'Transcript');
+
+    const manifest = loadManifest(manifestPath);
+    validateManifest(manifest);
+  
+    if (args.validate) {
+      console.log("Manifest is valid. No HTTP requests were made.");
+      process.exit(0);
+    }
+    
+    const suiteResult = await runSuite(manifest);
+
+    printConsoleReport(suiteResult, { verbose: args.verbose });
+
+    if (args.reportPath) {
+      writeJsonReport(args.reportPath, suiteResult);
+    }
+
+    if (args.transcriptPath) {
+      writeHttpTranscript(args.transcriptPath, suiteResult);
+    }
+
+    process.exit(suiteResult.summary.failed > 0 ? 1 : 0);
+  } catch (error) {
+    console.error(`ERROR: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+function parseArgs(argv) {
+  const args = {
+    manifestPath: null,
+    verbose: false,
+    validate: false,
+    reportPath: null,
+    transcriptPath: null
+  };
+
+  if (argv.length === 0) {
+    printUsage();
+    process.exit(1);
+  }
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    if (arg === '--help' || arg === '-h') {
+      printUsage();
+      process.exit(0);
+    }
+
+    if (arg === '--verbose' || arg === '-v') {
+      args.verbose = true;
+      continue;
+    }
+
+    if (arg === "--validate" || arg === '-c') {
+      args.validate = true;
+      continue;
+    }
+    
+    if (arg === '--report' || arg === '-r') {
+      const reportPath = requireOptionValue(arg, argv[i + 1]);
+      args.reportPath = reportPath;
+      i += 1;
+      continue;
+    }
+
+    if (arg === '--transcript' || arg === '-t') {
+      const transcriptPath = requireOptionValue(arg, argv[i + 1]);
+      args.transcriptPath = transcriptPath;
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+
+    if (!args.manifestPath) {
+      args.manifestPath = arg;
+      continue;
+    }
+
+    throw new Error(`Unexpected argument: ${arg}`);
+  }
+
+  if (!args.manifestPath) {
+    throw new Error('Missing manifest file path.');
+  }
+
+  return args;
+}
+
+function requireOptionValue(option, value) {
+  if (!value || value.startsWith('-')) {
+    throw new Error(`${option} requires a file path.`);
+  }
+
+  return value;
+}
+
+function printUsage() {
+  console.log('Usage:');
+  console.log('  tram <manifest-file> [options]');
+  console.log('');
+  console.log('Options:');
+  console.log('  -v, --verbose              Print passing assertion details');
+  console.log('  -r, --report <file>        Write JSON report to file');
+  console.log('  -t, --transcript <file>    Write HTTP transcript to file');
+  console.log('  -c, --validate             Validate the manifest without making HTTP requests');
+  console.log('  -h, --help                 Show help');
+  console.log('');
+  console.log('Examples:');
+  console.log('  tram api-tests.json --validate');
+  console.log('  tram api-tests.json');
+  console.log('  tram api-tests.json --verbose');
+  console.log('  tram api-tests.json --report results.json');
+  console.log('  tram api-tests.json --transcript transcript.http');
+}
+
+function validateManifestPath(manifestPath) {
+  const fullPath = path.resolve(process.cwd(), manifestPath);
+
+  if (!fs.existsSync(fullPath)) {
+    throw new Error(`Manifest file not found: ${fullPath}`);
+  }
+
+  const stats = fs.statSync(fullPath);
+
+  if (!stats.isFile()) {
+    throw new Error(`Manifest path is not a file: ${fullPath}`);
+  }
+
+  return fullPath;
+}
+
+function validateOutputPath(outputPath, label) {
+  if (!outputPath) return;
+
+  const fullPath = path.resolve(process.cwd(), outputPath);
+  const directory = path.dirname(fullPath);
+
+  if (!fs.existsSync(directory)) {
+    throw new Error(`${label} directory does not exist: ${directory}`);
+  }
+
+  const stats = fs.statSync(directory);
+
+  if (!stats.isDirectory()) {
+    throw new Error(`${label} path parent is not a directory: ${directory}`);
+  }
+}
+
+function loadManifest(manifestPath) {
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (error) {
+    throw new Error(`Unable to read manifest JSON: ${error.message}`);
+  }
+}
+
+const VALID_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+const VALID_BODY_TYPES = ['json', 'form', 'text'];
+
+function validateManifest(manifest) {
+  const errors = [];
+
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    errors.push('Manifest must be a JSON object.');
+  }
+
+  if (
+    manifest?.manifestVersion &&
+    !SUPPORTED_MANIFEST_VERSIONS.includes(manifest.manifestVersion)
+  ) {
+    errors.push(
+      `Unsupported manifestVersion ${manifest.manifestVersion}. ` +
+      `Supported versions are ${SUPPORTED_MANIFEST_VERSIONS.join(', ')}.`
+    );
+  }
+
+  if (!manifest?.config || typeof manifest.config !== 'object' || Array.isArray(manifest.config)) {
+    errors.push('Manifest requires config object.');
+  } else if (!manifest.config.baseUrl) {
+    errors.push('Manifest requires config.baseUrl.');
+  }
+
+  if (!Array.isArray(manifest?.tests)) {
+    errors.push('Manifest requires tests array.');
+  } else {
+    validateTests(manifest.tests, errors);
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`Manifest validation failed:\n- ${errors.join('\n- ')}`);
+  }
+}
+
+function validateTests(tests, errors) {
+  const seenIds = new Set();
+
+  tests.forEach((test, index) => {
+    const prefix = `tests[${index}]`;
+
+    if (!test || typeof test !== 'object' || Array.isArray(test)) {
+      errors.push(`${prefix} must be an object.`);
+      return;
+    }
+
+    if (test.id) {
+      if (seenIds.has(test.id)) {
+        errors.push(`${prefix}.id duplicates "${test.id}".`);
+      }
+      seenIds.add(test.id);
+    }
+
+    if (!test.name) {
+      errors.push(`${prefix} missing name.`);
+    }
+
+    if (!test.method) {
+      errors.push(`${prefix} missing method.`);
+    } else if (!VALID_METHODS.includes(String(test.method).toUpperCase())) {
+      errors.push(`${prefix}.method unsupported HTTP method: ${test.method}.`);
+    }
+
+    if (!test.path) {
+      errors.push(`${prefix} missing path.`);
+    } else if (typeof test.path !== 'string') {
+      errors.push(`${prefix}.path must be a string.`);
+    }
+
+    if (!test.expect || typeof test.expect !== 'object' || Array.isArray(test.expect)) {
+      errors.push(`${prefix} missing expect object.`);
+    }
+
+    if (test.bodyType && !VALID_BODY_TYPES.includes(test.bodyType)) {
+      errors.push(`${prefix}.bodyType unsupported value: ${test.bodyType}.`);
+    }
+
+    validateCapture(test.capture, `${prefix}.capture`, errors);
+  });
+}
+
+function validateCapture(capture, prefix, errors) {
+  if (capture === undefined) return;
+
+  if (!capture || typeof capture !== 'object' || Array.isArray(capture)) {
+    errors.push(`${prefix} must be an object.`);
+    return;
+  }
+
+  for (const [name, spec] of Object.entries(capture)) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+      errors.push(`${prefix}.${name} has invalid capture name.`);
+    }
+
+    if (typeof spec === 'string') {
+      validateCapturePath(spec, `${prefix}.${name}`, errors);
+      continue;
+    }
+
+    if (!spec || typeof spec !== 'object' || Array.isArray(spec)) {
+      errors.push(`${prefix}.${name} must be a string or object.`);
+      continue;
+    }
+
+    if (typeof spec.from !== 'string') {
+      errors.push(`${prefix}.${name}.from must be a string.`);
+    } else {
+      validateCapturePath(spec.from, `${prefix}.${name}.from`, errors);
+    }
+
+    if (spec.optional !== undefined && typeof spec.optional !== 'boolean') {
+      errors.push(`${prefix}.${name}.optional must be a boolean.`);
+    }
+  }
+}
+
+function validateCapturePath(capturePath, prefix, errors) {
+  if (!capturePath) {
+    errors.push(`${prefix} capture path must not be empty.`);
+    return;
+  }
+
+  if (
+    capturePath !== 'status' &&
+    capturePath !== 'rawBody' &&
+    !capturePath.startsWith('body.') &&
+    !capturePath.startsWith('headers.')
+  ) {
+    errors.push(`${prefix} unsupported capture path: ${capturePath}.`);
+  }
+}
+
+async function runSuite(manifest) {
+  const results = [];
+  const tests = manifest.tests || [];
+  const runtimeData = initializeRuntimeData(manifest.data || {});
+  const runtimeCapture = {};
+
+  for (let index = 0; index < tests.length; index += 1) {
+    const test = tests[index];
+    const testResult = await runTest({ manifest, runtimeData, runtimeCapture, test, index });
+    results.push(testResult);
+  }
+
+  return {
+    name: manifest.name || 'HTTP API Tests',
+    manifestVersion: manifest.manifestVersion || SUPPORTED_MANIFEST_VERSION,
+    version: manifest.version || null,
+    description: manifest.description || null,
+    author: manifest.author || null,
+    created: manifest.created || null,
+    updated: manifest.updated || null,
+    tags: Array.isArray(manifest.tags) ? manifest.tags : [],
+    summary: summarize(results),
+    results
+  };
+}
+
+async function runTest({ manifest, runtimeData, runtimeCapture, test, index }) {
+  const id = test.id || `test-${index + 1}`;
+  const enabled = test.enabled !== false;
+
+  if (!enabled) {
+    return {
+      id,
+      name: test.name || id,
+      enabled: false,
+      skipped: true,
+      passed: true,
+      method: test.method || null,
+      path: test.path || null,
+      status: null,
+      durationMs: 0,
+      assertions: []
+    };
+  }
+
+  validateTest(test, index);
+
+  const started = Date.now();
+  let request = null;
+
+  try {
+    request = buildRequest({ manifest, runtimeData, runtimeCapture, test });
+    const response = await executeRequest(request, manifest.config.timeoutMs);
+    const durationMs = Date.now() - started;
+    const resolvedExpect = resolveRuntimeTokens(
+      resolveValue(test.expect, runtimeData, runtimeCapture),
+      runtimeData,
+      runtimeCapture
+    );
+    const assertions = evaluateExpectations({ expect: resolvedExpect, response });
+    const expectationsPassed = assertions.every((assertion) => assertion.passed);
+    const captureAssertions = expectationsPassed
+      ? applyCapture(test.capture, response, runtimeCapture)
+      : [];
+    const allAssertions = assertions.concat(captureAssertions);
+    const passed = allAssertions.every((assertion) => assertion.passed);
+
+    return {
+      id,
+      name: test.name,
+      enabled: true,
+      skipped: false,
+      passed,
+      type: test.type || null,
+      tags: Array.isArray(test.tags) ? test.tags : [],
+      rationale: test.rationale || null,
+      method: request.method,
+      path: request.path,
+      url: request.url,
+      status: response.status,
+      durationMs,
+      request: requestForReport(request),
+      response: responseForReport(response),
+      assertions: allAssertions
+    };
+  } catch (error) {
+    const durationMs = Date.now() - started;
+
+    return {
+      id,
+      name: test.name,
+      enabled: true,
+      skipped: false,
+      passed: false,
+      type: test.type || null,
+      tags: Array.isArray(test.tags) ? test.tags : [],
+      rationale: test.rationale || null,
+      method: request ? request.method : (test.method || null),
+      path: request ? request.path : (test.path || null),
+      url: request ? request.url : null,
+      status: null,
+      durationMs,
+      request: request ? requestForReport(request) : null,
+      response: null,
+      assertions: [
+        {
+          passed: false,
+          type: 'request',
+          target: 'http',
+          expected: 'successful HTTP request',
+          actual: error.message,
+          message: `Request failed: ${error.message}`
+        }
+      ]
+    };
+  }
+}
+
+function validateTest(test, index) {
+  const label = test.name || `test at index ${index}`;
+
+  if (!test.name) throw new Error(`Test at index ${index} requires name.`);
+  if (!test.method) throw new Error(`${label} requires method.`);
+  if (!test.path) throw new Error(`${label} requires path.`);
+  if (!test.expect || typeof test.expect !== 'object') {
+    throw new Error(`${label} requires expect object.`);
+  }
+}
+
+function buildRequest({ manifest, runtimeData, runtimeCapture, test }) {
+  const config = manifest.config || {};
+
+  const method = String(test.method || 'GET').toUpperCase();
+  const headers = resolveRuntimeTokens(
+    resolveValue(
+      {
+        ...(config.defaultHeaders || {}),
+        ...(test.headers || {})
+      },
+      runtimeData,
+      runtimeCapture
+    ),
+    runtimeData,
+    runtimeCapture
+  );
+
+  const query = resolveRuntimeTokens(
+    resolveValue(test.query, runtimeData, runtimeCapture),
+    runtimeData,
+    runtimeCapture
+  );
+  const requestPath = resolveRuntimeTokens(
+    resolveValue(test.path, runtimeData, runtimeCapture),
+    runtimeData,
+    runtimeCapture
+  );
+  const url = buildUrl(config.baseUrl, requestPath, query, runtimeData);
+
+  const request = {
+    method,
+    path: requestPath,
+    url,
+    headers,
+    body: undefined,
+    bodyType: null
+  };
+
+  if (Object.prototype.hasOwnProperty.call(test, 'body')) {
+    const bodyType = test.bodyType || 'json';
+    const resolvedBody = resolveRuntimeTokens(
+      resolveValue(test.body, runtimeData, runtimeCapture),
+      runtimeData,
+      runtimeCapture
+    );
+
+    request.bodyType = bodyType;
+    request.body = encodeBody(resolvedBody, bodyType, request.headers);
+  }
+
+  return request;
+}
+
+function encodeBody(body, bodyType, headers) {
+  switch (bodyType) {
+    case 'json':
+      if (!hasHeader(headers, 'content-type')) {
+        headers['content-type'] = 'application/json';
+      }
+      return JSON.stringify(body);
+
+    case 'form':
+      if (!hasHeader(headers, 'content-type')) {
+        headers['content-type'] = 'application/x-www-form-urlencoded';
+      }
+      return encodeFormBody(body);
+
+    case 'text':
+      if (!hasHeader(headers, 'content-type')) {
+        headers['content-type'] = 'text/plain';
+      }
+      return typeof body === 'string' ? body : String(body);
+
+    default:
+      throw new Error(`Unsupported bodyType: ${bodyType}`);
+  }
+}
+
+function encodeFormBody(body) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    throw new Error('bodyType "form" requires body to be an object.');
+  }
+
+  const params = new URLSearchParams();
+
+  for (const [key, value] of Object.entries(body)) {
+    if (value === undefined || value === null) continue;
+    params.set(key, String(value));
+  }
+
+  return params.toString();
+}
+
+function buildUrl(baseUrl, requestPath, query, runtimeData) {
+  const url = new URL(requestPath, ensureTrailingSlash(baseUrl));
+
+  if (query && typeof query === 'object') {
+    for (const [key, value] of Object.entries(query)) {
+      if (value === undefined || value === null) continue;
+      url.searchParams.set(key, String(resolveRuntimeTokens(value, runtimeData)));
+    }
+  }
+
+  return url.toString();
+}
+
+function ensureTrailingSlash(value) {
+  return String(value).endsWith('/') ? value : `${value}/`;
+}
+
+async function executeRequest(request, timeoutMs = 5000) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(request.url, {
+      method: request.method,
+      headers: request.headers,
+      body: request.body,
+      signal: controller.signal
+    });
+
+    const text = await response.text();
+    const headers = headersToObject(response.headers);
+    const body = parseBody(text, headers);
+
+    return {
+      status: response.status,
+      headers,
+      body,
+      rawBody: text
+    };
+  } catch (error) {
+    if (error.name === 'AbortError') {
+      throw new Error(`Request timed out after ${timeoutMs}ms`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function parseBody(text, headers) {
+  if (!text) return null;
+
+  const contentType = getHeaderValue(headers, 'content-type') || '';
+
+  if (contentType.includes('application/json') || looksLikeJson(text)) {
+    try {
+      return JSON.parse(text);
+    } catch (_error) {
+      return text;
+    }
+  }
+
+  return text;
+}
+
+function looksLikeJson(text) {
+  const trimmed = text.trim();
+  return trimmed.startsWith('{') || trimmed.startsWith('[');
+}
+
+function headersToObject(headers) {
+  const result = {};
+  headers.forEach((value, key) => {
+    result[key.toLowerCase()] = value;
+  });
+  return result;
+}
+
+function initializeRuntimeData(data) {
+  return resolveBuiltInTokens(clone(data));
+}
+
+function resolveValue(value, runtimeData, runtimeCapture = {}) {
+  if (typeof value === 'string') {
+    if (value.startsWith('$data.')) {
+      const key = value.slice('$data.'.length);
+
+      if (Object.prototype.hasOwnProperty.call(runtimeData, key)) {
+        return clone(runtimeData[key]);
+      }
+
+      const resolved = getByPath(runtimeData, key);
+
+      if (!resolved.exists) {
+        throw new Error(`Data reference not found: ${value}`);
+      }
+
+      return clone(resolved.value);
+    }
+
+    if (value.startsWith('$capture.')) {
+      const key = value.slice('$capture.'.length);
+      const resolved = getByPath(runtimeCapture, key);
+
+      if (!resolved.exists) {
+        throw new Error(`Capture reference not found: ${value}`);
+      }
+
+      return clone(resolved.value);
+    }
+
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => resolveValue(item, runtimeData, runtimeCapture));
+  }
+
+  if (value && typeof value === 'object') {
+    const result = {};
+    for (const [key, child] of Object.entries(value)) {
+      result[key] = resolveValue(child, runtimeData, runtimeCapture);
+    }
+    return result;
+  }
+
+  return clone(value);
+}
+
+function resolveRuntimeTokens(value, runtimeData, runtimeCapture = {}) {
+  if (typeof value === 'string') {
+    return value.replace(/\$\{([^}]+)\}/g, (_match, tokenName) => {
+      if (tokenName.startsWith('data.')) {
+        const dataPath = tokenName.slice('data.'.length);
+        const resolved = getByPath(runtimeData, dataPath);
+
+        if (!resolved.exists) {
+          throw new Error(`Data reference not found: ${tokenName}`);
+        }
+
+        return String(resolved.value);
+      }
+
+      if (tokenName.startsWith('capture.')) {
+        const capturePath = tokenName.slice('capture.'.length);
+        const resolved = getByPath(runtimeCapture, capturePath);
+
+        if (!resolved.exists) {
+          throw new Error(`Capture reference not found: ${tokenName}`);
+        }
+
+        return String(resolved.value);
+      }
+
+      return generateToken(tokenName);
+    });
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => resolveRuntimeTokens(item, runtimeData, runtimeCapture));
+  }
+
+  if (value && typeof value === 'object') {
+    const result = {};
+    for (const [key, child] of Object.entries(value)) {
+      result[key] = resolveRuntimeTokens(child, runtimeData, runtimeCapture);
+    }
+    return result;
+  }
+
+  return value;
+}
+
+function resolveBuiltInTokens(value) {
+  if (typeof value === 'string') {
+    return value.replace(/\$\{([^}]+)\}/g, (_match, tokenName) => {
+      if (tokenName.startsWith('data.')) {
+        return `\${${tokenName}}`;
+      }
+
+      return generateToken(tokenName);
+    });
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => resolveBuiltInTokens(item));
+  }
+
+  if (value && typeof value === 'object') {
+    const result = {};
+    for (const [key, child] of Object.entries(value)) {
+      result[key] = resolveBuiltInTokens(child);
+    }
+    return result;
+  }
+
+  return value;
+}
+
+function getByPath(source, dotPath) {
+  if (!dotPath) {
+    return { exists: true, value: source };
+  }
+
+  const parts = String(dotPath).split('.');
+  let current = source;
+
+  for (const part of parts) {
+    if (current === null || current === undefined) {
+      return { exists: false, value: undefined };
+    }
+
+    if (!Object.prototype.hasOwnProperty.call(Object(current), part)) {
+      return { exists: false, value: undefined };
+    }
+
+    current = current[part];
+  }
+
+  return { exists: true, value: current };
+}
+
+function applyCapture(capture, response, runtimeCapture) {
+  if (capture === undefined) return [];
+
+  const assertions = [];
+
+  for (const [name, spec] of Object.entries(capture)) {
+    const captureSpec = normalizeCaptureSpec(spec);
+    const resolved = getCaptureValue(response, captureSpec.from);
+
+    if (!resolved.exists) {
+      const passed = captureSpec.optional === true;
+      assertions.push({
+        passed,
+        type: 'capture',
+        target: name,
+        expected: captureSpec.from,
+        actual: undefined,
+        message: passed
+          ? `Optional capture skipped: ${name} from ${captureSpec.from}`
+          : `Capture failed: ${name} not found at ${captureSpec.from}`
+      });
+      continue;
+    }
+
+    runtimeCapture[name] = clone(resolved.value);
+    assertions.push({
+      passed: true,
+      type: 'capture',
+      target: name,
+      expected: captureSpec.from,
+      actual: resolved.value,
+      message: `Captured ${name} from ${captureSpec.from}`
+    });
+  }
+
+  return assertions;
+}
+
+function normalizeCaptureSpec(spec) {
+  if (typeof spec === 'string') {
+    return { from: spec, optional: false };
+  }
+
+  return {
+    from: spec.from,
+    optional: spec.optional === true
+  };
+}
+
+function getCaptureValue(response, capturePath) {
+  if (capturePath === 'status') {
+    return { exists: true, value: response.status };
+  }
+
+  if (capturePath === 'rawBody') {
+    return { exists: true, value: response.rawBody };
+  }
+
+  if (capturePath.startsWith('body.')) {
+    return getByPath(response.body, capturePath.slice('body.'.length));
+  }
+
+  if (capturePath.startsWith('headers.')) {
+    const headerName = capturePath.slice('headers.'.length).toLowerCase();
+    const value = getHeaderValue(response.headers, headerName);
+    return {
+      exists: value !== undefined,
+      value
+    };
+  }
+
+  return { exists: false, value: undefined };
+}
+
+function generateToken(tokenName) {
+  switch (tokenName) {
+    case 'randomId':
+      return Math.random().toString(36).slice(2);
+    case 'timestamp':
+      return new Date().toISOString();
+    case 'uuid':
+      return cryptoRandomUuid();
+    case 'randomEmail':
+      return `test-${Math.random().toString(36).slice(2)}@example.com`;
+    default:
+      return `\${${tokenName}}`;
+  }
+}
+
+function cryptoRandomUuid() {
+  if (global.crypto && typeof global.crypto.randomUUID === 'function') {
+    return global.crypto.randomUUID();
+  }
+
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (char) => {
+    const random = Math.floor(Math.random() * 16);
+    const value = char === 'x' ? random : (random & 0x3) | 0x8;
+    return value.toString(16);
+  });
+}
+
+function summarize(results) {
+  const summary = {
+    total: results.length,
+    passed: 0,
+    failed: 0,
+    skipped: 0
+  };
+
+  for (const result of results) {
+    if (result.skipped) summary.skipped += 1;
+    else if (result.passed) summary.passed += 1;
+    else summary.failed += 1;
+  }
+
+  return summary;
+}
+
+function printConsoleReport(suiteResult, options = {}) {
+  const verbose = options.verbose === true;
+
+  console.log(suiteResult.name);
+  console.log('');
+
+  for (const result of suiteResult.results) {
+    if (result.skipped) {
+      console.log(`- ${result.name} (skipped)`);
+      continue;
+    }
+
+    const marker = result.passed ? '✓' : '✗';
+    console.log(`${marker} ${result.name}`);
+
+    if (!result.passed || verbose) {
+      console.log(`  ${result.method} ${result.path}`);
+      if (result.status !== null && result.status !== undefined) {
+        console.log(`  Status: ${result.status}`);
+      }
+
+      const assertionsToPrint = verbose
+        ? result.assertions
+        : result.assertions.filter((assertion) => !assertion.passed);
+
+      for (const assertion of assertionsToPrint) {
+        const assertionMarker = assertion.passed ? '✓' : '✗';
+        console.log(`  ${assertionMarker} ${assertion.message}`);
+      }
+    }
+  }
+
+  console.log('');
+  console.log(
+    `Summary: ${suiteResult.summary.passed} passed, ${suiteResult.summary.failed} failed, ${suiteResult.summary.skipped} skipped, ${suiteResult.summary.total} total`
+  );
+}
+
+function writeJsonReport(reportPath, suiteResult) {
+  const fullPath = path.resolve(process.cwd(), reportPath);
+  fs.writeFileSync(fullPath, `${JSON.stringify(suiteResult, null, 2)}\n`, 'utf8');
+}
+
+
+function writeHttpTranscript(transcriptPath, suiteResult) {
+  const fullPath = path.resolve(process.cwd(), transcriptPath);
+  fs.writeFileSync(fullPath, renderHttpTranscript(suiteResult), 'utf8');
+}
+
+function renderHttpTranscript(suiteResult) {
+  const lines = [];
+
+  lines.push('TRAM HTTP Transcript');
+  lines.push(`Suite: ${suiteResult.name}`);
+  lines.push(`Generated: ${new Date().toISOString()}`);
+  lines.push('');
+
+  for (const result of suiteResult.results) {
+    if (result.skipped) {
+      continue;
+    }
+
+    lines.push('============================================================');
+    lines.push(`${result.name} (${result.id})`);
+    lines.push('');
+    lines.push(renderTranscriptRequest(result.request));
+    lines.push('');
+    lines.push(renderTranscriptResponse(result.response));
+
+    const captureAssertions = (result.assertions || []).filter((assertion) => assertion.type === 'capture');
+    if (captureAssertions.length > 0) {
+      lines.push('');
+      lines.push('--- Captures ------------------------------------------------');
+      for (const assertion of captureAssertions) {
+        if (assertion.passed) {
+          lines.push(`${assertion.target} = ${formatTranscriptValue(assertion.actual)}`);
+        } else {
+          lines.push(`${assertion.target} = <not captured>`);
+        }
+      }
+    }
+
+    lines.push('');
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function renderTranscriptRequest(request) {
+  if (!request) {
+    return '> REQUEST UNAVAILABLE';
+  }
+
+  const url = new URL(request.url);
+  const lines = [];
+
+  lines.push(`> ${request.method} ${url.pathname}${url.search} HTTP/1.1`);
+  lines.push(`> Host: ${url.host}`);
+
+  for (const [name, value] of Object.entries(request.headers || {})) {
+    lines.push(`> ${name}: ${redactHeaderValue(name, value)}`);
+  }
+
+  if (request.body !== null && request.body !== undefined) {
+    lines.push('>');
+    lines.push(prefixTranscriptBody(formatTranscriptBody(request.body), '> '));
+  }
+
+  return lines.join('\n');
+}
+
+function renderTranscriptResponse(response) {
+  if (!response) {
+    return '< REQUEST FAILED';
+  }
+
+  const lines = [];
+
+  lines.push(`< HTTP/1.1 ${response.status}`);
+
+  for (const [name, value] of Object.entries(response.headers || {})) {
+    lines.push(`< ${name}: ${redactHeaderValue(name, value)}`);
+  }
+
+  if (response.rawBody) {
+    lines.push('<');
+    lines.push(prefixTranscriptBody(formatTranscriptBody(response.body), '< '));
+  }
+
+  return lines.join('\n');
+}
+
+function formatTranscriptBody(value) {
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  return JSON.stringify(value, null, 2);
+}
+
+function prefixTranscriptBody(value, prefix) {
+  return String(value)
+    .split('\n')
+    .map((line) => `${prefix}${line}`)
+    .join('\n');
+}
+
+function formatTranscriptValue(value) {
+  if (typeof value === 'string') {
+    return JSON.stringify(value);
+  }
+
+  return JSON.stringify(value, null, 2);
+}
+
+function redactHeaderValue(name, value) {
+  const sensitiveHeaders = new Set(['authorization', 'cookie', 'set-cookie', 'x-api-key']);
+
+  if (sensitiveHeaders.has(String(name).toLowerCase())) {
+    return '[redacted]';
+  }
+
+  return value;
+}
+
+function redactHeaders(headers) {
+  return Object.fromEntries(
+    Object.entries(headers || {}).map(([name, value]) => [name, redactHeaderValue(name, value)])
+  );
+}
+
+function requestForReport(request) {
+  return {
+    method: request.method,
+    url: request.url,
+    headers: redactHeaders(request.headers),
+    bodyType: request.bodyType,
+    body: request.body ? safeParseRequestBody(request.body, request.bodyType) : null
+  };
+}
+
+function safeParseRequestBody(value, bodyType) {
+  if (bodyType === 'json') {
+    try {
+      return JSON.parse(value);
+    } catch (_error) {
+      return value;
+    }
+  }
+
+  if (bodyType === 'form') {
+    return Object.fromEntries(new URLSearchParams(value));
+  }
+
+  return value;
+}
+
+function responseForReport(response) {
+  return {
+    status: response.status,
+    headers: redactHeaders(response.headers),
+    body: response.body,
+    rawBody: response.rawBody
+  };
+}
+
+function hasHeader(headers, name) {
+  const normalized = name.toLowerCase();
+  return Object.keys(headers).some((key) => key.toLowerCase() === normalized);
+}
+
+function getHeaderValue(headers, name) {
+  const normalized = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers || {})) {
+    if (key.toLowerCase() === normalized) return value;
+  }
+  return undefined;
+}
+
+function clone(value) {
+  if (value === undefined) return undefined;
+  return JSON.parse(JSON.stringify(value));
+}
+
+main();
+