@typespec/spector 0.1.0-alpha.0

package/dist/src/utils/misc-utils.d.ts

@@ -0,0 +1,8 @@
+export declare function ensureScenariosPathExists(scenariosPath: string): Promise<void>;
+export declare function getCommit(path: string): string;
+export interface PackageJson {
+    name: string;
+    version: string;
+}
+export declare function getPackageJson(path: string): Promise<PackageJson | undefined>;
+//# sourceMappingURL=misc-utils.d.ts.map

package/dist/src/utils/misc-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"misc-utils.d.ts","sourceRoot":"","sources":["../../../src/utils/misc-utils.ts"],"names":[],"mappings":"AAKA,wBAAsB,yBAAyB,CAAC,aAAa,EAAE,MAAM,iBASpE;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CASnF"}

package/dist/src/utils/misc-utils.js

@@ -0,0 +1,47 @@
+import { execSync } from "child_process";
+import { readFile, stat } from "fs/promises";
+import { dirname, join } from "path";
+import { logger } from "../logger.js";
+export async function ensureScenariosPathExists(scenariosPath) {
+    try {
+        const stats = await stat(scenariosPath);
+        if (!stats.isDirectory()) {
+            throw new Error(`Scenarios path ${scenariosPath} is not a directory.`);
+        }
+    }
+    catch (e) {
+        throw new Error(`Scenarios path ${scenariosPath} doesn't exists.`);
+    }
+}
+export function getCommit(path) {
+    return execSync("git rev-parse HEAD", { cwd: path }).toString().trim();
+}
+export async function getPackageJson(path) {
+    logger.debug(`Loading package json for path "${path}"`);
+    const projectRoot = await findProjectRoot(path);
+    if (projectRoot === undefined) {
+        return undefined;
+    }
+    logger.debug(`Found project root "${projectRoot}"`);
+    const packageJsonPath = join(projectRoot, "package.json");
+    return JSON.parse((await readFile(packageJsonPath, "utf-8")).toString());
+}
+async function findProjectRoot(path) {
+    let current = path;
+    while (true) {
+        const pkgPath = join(current, "package.json");
+        try {
+            const stats = await stat(pkgPath);
+            if (stats?.isFile()) {
+                return current;
+            }
+        }
+        catch { }
+        const parent = dirname(current);
+        if (parent === current) {
+            return undefined;
+        }
+        current = parent;
+    }
+}
+//# sourceMappingURL=misc-utils.js.map

package/dist/src/utils/misc-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"misc-utils.js","sourceRoot":"","sources":["../../../src/utils/misc-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,aAAqB;IACnE,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,CAAC;QACxC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,kBAAkB,aAAa,sBAAsB,CAAC,CAAC;QACzE,CAAC;IACH,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,kBAAkB,aAAa,kBAAkB,CAAC,CAAC;IACrE,CAAC;AACH,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,QAAQ,CAAC,oBAAoB,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC;AACzE,CAAC;AAOD,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAY;IAC/C,MAAM,CAAC,KAAK,CAAC,kCAAkC,IAAI,GAAG,CAAC,CAAC;IACxD,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;IAChD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,CAAC,KAAK,CAAC,uBAAuB,WAAW,GAAG,CAAC,CAAC;IACpD,MAAM,eAAe,GAAG,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;IAC1D,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;AAC3E,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,IAAY;IACzC,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;QAC9C,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC;YAClC,IAAI,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC;gBACpB,OAAO,OAAO,CAAC;YACjB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC,CAAA,CAAC;QAEV,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAChC,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YACvB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,GAAG,MAAM,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/src/utils/path-utils.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizePath(path: string): string;
+//# sourceMappingURL=path-utils.d.ts.map

package/dist/src/utils/path-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../../../src/utils/path-utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/dist/src/utils/path-utils.js

@@ -0,0 +1,4 @@
+export function normalizePath(path) {
+    return path.replace(/\\/g, "/");
+}
+//# sourceMappingURL=path-utils.js.map

package/dist/src/utils/path-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utils.js","sourceRoot":"","sources":["../../../src/utils/path-utils.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAClC,CAAC"}

package/dist/src/utils/request-utils.d.ts

@@ -0,0 +1,3 @@
+import { Request } from "express";
+export declare const getRequestBaseUrl: (request: Request) => string;
+//# sourceMappingURL=request-utils.d.ts.map

package/dist/src/utils/request-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-utils.d.ts","sourceRoot":"","sources":["../../../src/utils/request-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC,eAAO,MAAM,iBAAiB,YAAa,OAAO,KAAG,MACL,CAAC"}

package/dist/src/utils/request-utils.js

@@ -0,0 +1,2 @@
+export const getRequestBaseUrl = (request) => `${request.protocol}://${request.get("host")}`;
+//# sourceMappingURL=request-utils.js.map

package/dist/src/utils/request-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-utils.js","sourceRoot":"","sources":["../../../src/utils/request-utils.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,OAAgB,EAAU,EAAE,CAC5D,GAAG,OAAO,CAAC,QAAQ,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC"}

package/generated-defs/TypeSpec.Spector.ts

@@ -0,0 +1,46 @@
+import type {
+  DecoratorContext,
+  Interface,
+  Model,
+  Namespace,
+  Operation,
+  Type,
+} from "@typespec/compiler";
+
+/**
+ * Setup the boilerplate for a scenario service(server endpoint, etc.)
+ */
+export type ScenarioServiceDecorator = (
+  context: DecoratorContext,
+  target: Namespace,
+  route: string,
+  options?: Type,
+) => void;
+
+/**
+ * Mark an operation, interface or namespace as a scenario. All containing operations will be part of the same scenario.
+ */
+export type ScenarioDecorator = (
+  context: DecoratorContext,
+  target: Namespace | Interface | Operation,
+  name?: string,
+) => void;
+
+/**
+ * Specify documentation on how to implement this scenario.
+ *
+ * @param doc Documentation
+ * @param formatArgs Format arguments
+ */
+export type ScenarioDocDecorator = (
+  context: DecoratorContext,
+  target: Namespace | Interface | Operation,
+  doc: string,
+  formatArgs?: Model,
+) => void;
+
+export type TypeSpecSpectorDecorators = {
+  scenarioService: ScenarioServiceDecorator;
+  scenario: ScenarioDecorator;
+  scenarioDoc: ScenarioDocDecorator;
+};

package/generated-defs/TypeSpec.Spector.ts-test.ts

@@ -0,0 +1,5 @@
+/** An error here would mean that the decorator is not exported or doesn't have the right name. */
+import { $decorators } from "@typespec/spector";
+import type { TypeSpecSpectorDecorators } from "./TypeSpec.Spector.js";
+/** An error here would mean that the exported decorator is not using the same signature. Make sure to have export const $decName: DecNameDecorator = (...) => ... */
+const _: TypeSpecSpectorDecorators = $decorators["TypeSpec.Spector"];

package/lib/main.tsp

@@ -0,0 +1,37 @@
+import "../dist/src/lib/tsp-index.js";
+
+using TypeSpec.Reflection;
+
+namespace TypeSpec.Spector;
+
+alias ScenarioServiceOptions = {
+  /**
+   * Version enum that would be used on the $versioned decorator
+   */
+  versioned?: Enum;
+};
+
+/**
+ * Setup the boilerplate for a scenario service(server endpoint, etc.)
+ */
+extern dec scenarioService(
+  target: Namespace,
+  route: valueof string,
+  options?: ScenarioServiceOptions
+);
+
+/**
+ * Mark an operation, interface or namespace as a scenario. All containing operations will be part of the same scenario.
+ */
+extern dec scenario(target: Namespace | Interface | Operation, name?: valueof string);
+
+/**
+ * Specify documentation on how to implement this scenario.
+ * @param doc Documentation
+ * @param formatArgs Format arguments
+ */
+extern dec scenarioDoc(
+  target: Namespace | Interface | Operation,
+  doc: valueof string,
+  formatArgs?: Model
+);

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@typespec/spector",
+  "version": "0.1.0-alpha.0",
+  "description": "Typespec Core Tool to validate, run mock api, collect coverage.",
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "typespec": "./lib/main.tsp"
+    }
+  },
+  "type": "module",
+  "bin": {
+    "tsp-spector": "./cmd/cli.mjs"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microsoft/typespec.git"
+  },
+  "author": "Microsoft",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/microsoft/typespec/issues"
+  },
+  "homepage": "https://github.com/microsoft/typespec#readme",
+  "dependencies": {
+    "@azure/identity": "~4.4.1",
+    "@types/js-yaml": "^4.0.5",
+    "ajv": "~8.17.1",
+    "axios": "^1.7.5",
+    "body-parser": "^1.20.3",
+    "deep-equal": "^2.2.0",
+    "express": "^4.21.1",
+    "express-promise-router": "^4.1.1",
+    "form-data": "^4.0.1",
+    "globby": "~14.0.2",
+    "jackspeak": "4.0.2",
+    "js-yaml": "^4.1.0",
+    "morgan": "^1.10.0",
+    "multer": "^1.4.5-lts.1",
+    "node-fetch": "^3.3.1",
+    "picocolors": "~1.1.0",
+    "source-map-support": "~0.5.21",
+    "winston": "^3.15.0",
+    "xml2js": "^0.6.2",
+    "yargs": "~17.7.2",
+    "@typespec/compiler": "~0.61.2",
+    "@typespec/http": "~0.61.0",
+    "@typespec/versioning": "~0.61.0",
+    "@typespec/rest": "~0.61.0",
+    "@typespec/spec-api": "~0.1.0-alpha.0",
+    "@typespec/spec-coverage-sdk": "~0.1.0-alpha.0"
+  },
+  "devDependencies": {
+    "@types/body-parser": "^1.19.2",
+    "@types/deep-equal": "^1.0.1",
+    "@types/express": "^5.0.0",
+    "@types/morgan": "^1.9.4",
+    "@types/multer": "^1.4.10",
+    "@types/node": "~22.7.5",
+    "@types/node-fetch": "^2.6.3",
+    "@types/xml2js": "^0.4.11",
+    "@types/yargs": "~17.0.33",
+    "rimraf": "~6.0.1",
+    "typescript": "~5.6.3",
+    "@typespec/tspd": "~0.46.0"
+  },
+  "scripts": {
+    "watch": "tsc -p ./tsconfig.build.json --watch",
+    "build": "npm run gen-extern-signature && tsc -p tsconfig.build.json",
+    "clean": "rimraf dist/ temp/",
+    "gen-extern-signature": "tspd --enable-experimental gen-extern-signature .",
+    "test": "vitest run",
+    "test:watch": "vitest -w",
+    "test:ui": "vitest --ui"
+  }
+}

package/src/actions/check-coverage.ts

@@ -0,0 +1,98 @@
+import { CoverageReport, ScenarioStatus } from "@typespec/spec-coverage-sdk";
+import { readFile, writeFile } from "fs/promises";
+import { loadSpecConfig } from "../config/config.js";
+import { createCoverageReport } from "../coverage/coverage-report.js";
+import { loadScenarioMockApis } from "../scenarios-resolver.js";
+import { createDiagnosticReporter, findFilesFromPattern } from "../utils/index.js";
+
+export interface CheckCoverageConfig {
+  scenariosPath: string;
+  configFile?: string;
+  coverageFiles: string[];
+  mergedCoverageFile: string;
+  ignoreNotImplemented?: boolean;
+  exitDueToPreviousError?: boolean;
+  hasMoreScenarios?: boolean;
+}
+
+export async function checkCoverage(config: CheckCoverageConfig): Promise<boolean> {
+  const inputCoverageFiles = (
+    await Promise.all(config.coverageFiles.map((x) => findFilesFromPattern(x)))
+  ).flat();
+
+  const results: Record<string, ScenarioStatus> = {};
+  const diagnosticsReporter = createDiagnosticReporter();
+  const scenarios = await loadScenarioMockApis(config.scenariosPath);
+
+  for (const scenarioName of Object.keys(scenarios)) {
+    results[scenarioName] = "not-implemented";
+  }
+
+  if (config.configFile) {
+    const [specConfig, diagnostics] = await loadSpecConfig(config.configFile);
+    diagnosticsReporter.reportDiagnostics(diagnostics);
+
+    for (const scenarioName of specConfig.unsupportedScenarios) {
+      results[scenarioName] = "not-supported";
+    }
+  }
+
+  for (const coverageFile of inputCoverageFiles) {
+    const content = await readFile(coverageFile);
+    const inputCoverage: CoverageReport = JSON.parse(content.toString());
+
+    for (const [scenarioName, scenarioStatus] of Object.entries(inputCoverage.results)) {
+      const existing = results[scenarioName];
+      if (existing === undefined) {
+        diagnosticsReporter.reportDiagnostic({
+          message: `Scenario ${scenarioName} with coverage in file "${coverageFile}" is not defined in the scenarios in path "${config.scenariosPath}".`,
+        });
+        continue;
+      }
+
+      switch (scenarioStatus) {
+        case "fail":
+          results[scenarioName] = "fail";
+          diagnosticsReporter.reportDiagnostic({
+            message: `Scenario ${scenarioName} failed in "${coverageFile}".`,
+          });
+          break;
+        case "pass":
+        case "not-applicable":
+        case "not-supported":
+          if (existing === "not-implemented") {
+            results[scenarioName] = scenarioStatus;
+          }
+          break;
+        case "not-implemented":
+        // nothing
+      }
+    }
+  }
+
+  if (!config.ignoreNotImplemented) {
+    for (const [scenarioName, scenarioStatus] of Object.entries(results)) {
+      if (scenarioStatus === "not-implemented") {
+        diagnosticsReporter.reportDiagnostic({
+          message: `Scenario ${scenarioName} is not implemented.`,
+        });
+      }
+    }
+  }
+
+  const coverageReport = createCoverageReport(config.scenariosPath, results);
+  await writeFile(config.mergedCoverageFile, JSON.stringify(coverageReport, null, 2));
+
+  if (diagnosticsReporter.diagnostics.length === 0) {
+    if (config.exitDueToPreviousError) {
+      process.exit(1);
+    }
+    return false;
+  } else {
+    if (config.hasMoreScenarios) {
+      return true;
+    } else {
+      process.exit(1);
+    }
+  }
+}

package/src/actions/generate-scenario-summary.ts

@@ -0,0 +1,63 @@
+import { readFile, writeFile } from "fs/promises";
+import pc from "picocolors";
+import prettier from "prettier";
+import type { Scenario, ScenarioEndpoint } from "../lib/decorators.js";
+import { logger } from "../logger.js";
+import { loadScenarios } from "../scenarios-resolver.js";
+
+export interface GenerateScenarioSummaryConfig {
+  scenariosPath: string;
+  outputFile: string;
+  overrideOutputFile?: boolean;
+}
+
+export async function generateScenarioSummary({
+  scenariosPath,
+  outputFile,
+  overrideOutputFile,
+}: GenerateScenarioSummaryConfig) {
+  const [scenarios, diagnostics] = await loadScenarios(scenariosPath);
+
+  if (diagnostics.length > 0) {
+    process.exit(-1);
+  }
+
+  let summary = await createScenarioSummary(scenarios);
+  if (overrideOutputFile) {
+    const existingContent = await readFile(outputFile, "utf-8");
+    summary = summary.replace(/# Spec Project summary/, "");
+    await writeFile(outputFile, `${existingContent}\n${summary}`);
+  } else {
+    await writeFile(outputFile, summary);
+  }
+  logger.info(`${pc.green("✓")} Scenario summary generated at ${outputFile}.`);
+}
+
+export function createScenarioSummary(scenarios: Scenario[]): Promise<string> {
+  const lines = [`# Spec Project summary`];
+
+  for (const scenario of scenarios.sort((a, b) => a.name.localeCompare(b.name))) {
+    lines.push(`### ${scenario.name}`);
+    lines.push("");
+    const endpoints = renderEndpoints(scenario.endpoints);
+    if (endpoints) {
+      lines.push(...endpoints);
+    }
+    lines.push("");
+    lines.push(`${scenario.scenarioDoc}`);
+    lines.push("");
+  }
+  const markdown = lines.join("\n");
+
+  return prettier.format(markdown, { parser: "markdown" });
+}
+
+function renderEndpoints(endpoints: ScenarioEndpoint[]) {
+  if (endpoints.length === 0) {
+    return undefined;
+  } else if (endpoints.length === 1) {
+    return [`- Endpoint: \`${endpoints[0].verb} ${endpoints[0].path}\``];
+  } else {
+    return [`- Endpoints:`, ...endpoints.map((x) => `  - \`${endpoints[0].verb} ${x.path}\``)];
+  }
+}

package/src/actions/helper.ts

@@ -0,0 +1,116 @@
+import { HttpMethod, ServiceRequestFile } from "@typespec/spec-api";
+import axios, { AxiosRequestConfig, AxiosResponse } from "axios";
+import FormData from "form-data";
+
+export interface ServiceRequest {
+  endPoint: string;
+  options?: {
+    requestBody?: any;
+    files?: ServiceRequestFile[];
+    config?: AxiosRequestConfig<any> | undefined;
+  };
+}
+
+function checkAndAddFormDataIfRequired(request: ServiceRequest) {
+  if (request.options?.config?.headers?.["Content-Type"] === "multipart/form-data") {
+    const formData = new FormData();
+    if (request.options?.requestBody) {
+      for (const key in request.options.requestBody) {
+        formData.append(key, JSON.stringify(request.options.requestBody[key]));
+      }
+    }
+    if (request.options.files) {
+      request.options.files.forEach((file) => {
+        formData.append(`${file.fieldname}`, file.buffer, {
+          filename: file.originalname,
+          contentType: file.mimetype,
+        });
+      });
+    }
+    request.options.requestBody = formData;
+    request.options.config = {
+      ...request.options.config,
+      headers: formData.getHeaders(),
+    };
+  }
+}
+
+function checkAndUpdateEndpoint(request: ServiceRequest) {
+  if (request.options?.config?.params) {
+    for (const key in request.options.config.params) {
+      request.endPoint = request.endPoint.replace(`:${key}`, request.options.config.params[key]);
+    }
+  }
+  request.endPoint = request.endPoint.replace(/\[:\]/g, ":");
+}
+
+export async function makeServiceCall(
+  serviceCallType: HttpMethod,
+  request: ServiceRequest,
+): Promise<AxiosResponse<any, any>> {
+  checkAndUpdateEndpoint(request);
+  checkAndAddFormDataIfRequired(request);
+  if (serviceCallType === "put") {
+    return await makePutCall(request);
+  }
+  if (serviceCallType === "post") {
+    return await makePostCall(request);
+  }
+  if (serviceCallType === "get") {
+    return await makeGetCall(request);
+  }
+  if (serviceCallType === "delete") {
+    return await makeDeleteCall(request);
+  }
+  if (serviceCallType === "head") {
+    return await makeHeadCall(request);
+  }
+  return await makePatchCall(request);
+}
+
+export async function makePutCall(request: ServiceRequest): Promise<AxiosResponse<any, any>> {
+  const response = await axios.put(
+    request.endPoint,
+    request.options?.requestBody,
+    request.options?.config,
+  );
+  return response;
+}
+
+export async function makePostCall(request: ServiceRequest): Promise<AxiosResponse<any, any>> {
+  const response = await axios.post(
+    request.endPoint,
+    request.options?.requestBody,
+    request.options?.config,
+  );
+  return response;
+}
+
+export async function makeGetCall(request: ServiceRequest): Promise<AxiosResponse<any, any>> {
+  const response = await axios.get(request.endPoint, request.options?.config);
+  return response;
+}
+
+export async function makePatchCall(request: ServiceRequest): Promise<AxiosResponse<any, any>> {
+  const response = await axios.patch(
+    request.endPoint,
+    request.options?.requestBody,
+    request.options?.config,
+  );
+  return response;
+}
+
+export async function makeDeleteCall(request: ServiceRequest): Promise<AxiosResponse<any, any>> {
+  const response = await axios.delete(request.endPoint, request.options?.config);
+  return response;
+}
+
+export async function makeHeadCall(request: ServiceRequest): Promise<AxiosResponse<any, any>> {
+  const response = await axios.head(request.endPoint, request.options?.config);
+  return response;
+}
+
+type EncodingType = "utf-8" | "base64" | "base64url" | "hex";
+export function uint8ArrayToString(bytes: Uint8Array, format: EncodingType): string {
+  return Buffer.from(bytes).toString(format);
+}

package/src/actions/index.ts

@@ -0,0 +1 @@
+export * from "./validate-scenarios.js";

package/src/actions/serve.ts

@@ -0,0 +1,88 @@
+import { spawn } from "child_process";
+import fetch from "node-fetch";
+import { resolve } from "path";
+import { MockApiApp } from "../app/app.js";
+import { AdminUrls } from "../constants.js";
+import { logger } from "../logger.js";
+import { ensureScenariosPathExists } from "../utils/index.js";
+
+export interface ServeConfig {
+  scenariosPath: string | string[];
+  coverageFile: string;
+  port: number;
+}
+
+export interface StopConfig {
+  port: number;
+}
+
+export async function serve(config: ServeConfig) {
+  if (Array.isArray(config.scenariosPath)) {
+    for (let idx = 0; idx < config.scenariosPath.length; idx++) {
+      config.scenariosPath[idx] = resolve(process.cwd(), config.scenariosPath[idx]);
+      await ensureScenariosPathExists(config.scenariosPath[idx]);
+    }
+  } else {
+    await ensureScenariosPathExists(config.scenariosPath);
+  }
+
+  const server = new MockApiApp({
+    port: config.port,
+    scenarioPath: config.scenariosPath,
+    coverageFile: config.coverageFile,
+  });
+  await server.start();
+}
+
+export async function startInBackground(config: ServeConfig) {
+  return new Promise<void>((resolve) => {
+    const [nodeExe, entrypoint] = process.argv;
+    logger.info(`Starting server in background at port ${config.port}`);
+    const scenariosPath = Array.isArray(config.scenariosPath)
+      ? config.scenariosPath.join(" ")
+      : config.scenariosPath;
+    const cp = spawn(
+      nodeExe,
+      [
+        entrypoint,
+        "serve",
+        scenariosPath,
+        "--port",
+        config.port.toString(),
+        "--coverageFile",
+        config.coverageFile,
+      ],
+      {
+        detached: true,
+        stdio: "ignore",
+      },
+    );
+    const exitListener = (exitCode: number) => {
+      logger.error(`Server exited within 1s with exit code ${exitCode}`);
+      process.exit(1);
+    };
+    cp.on("exit", exitListener);
+    setTimeout(() => {
+      cp.removeListener("exit", exitListener);
+      logger.info(`Stated server with pid: ${cp.pid}`);
+      cp.unref();
+      resolve();
+    }, 1000);
+  });
+}
+
+export async function stop(config: StopConfig) {
+  try {
+    await fetch(`http://localhost:${config.port}${AdminUrls.stop}`, {
+      method: "post",
+    });
+
+    logger.info(`Stopped server running at port  ${config.port}.`);
+  } catch (e: any) {
+    if (e.code === "ECONNREFUSED") {
+      logger.info(`No server running at port ${config.port}.`);
+    } else {
+      throw e;
+    }
+  }
+}