Counterfact Repl

Counterfact REPL Skill

Purpose

This skill enables AI agents to interact with a running Counterfact mock server through its Admin API. Counterfact provides programmable API mocks based on OpenAPI specifications, with a REPL for runtime manipulation. This skill exposes those capabilities programmatically via HTTP endpoints.

What is Counterfact?

Counterfact is a contract-driven mock API server that:

• Generates mock endpoints from OpenAPI specifications
• Provides a JavaScript REPL for runtime state manipulation
• Allows programmable behavior (not just static responses)
• Supports context objects for storing mock state
• Enables proxy mode to route requests to real APIs selectively

The REPL lets developers manipulate mock state in real-time using JavaScript. This skill exposes the same capabilities via HTTP API.

When to Use This Skill

Invoke this skill when the user:

• Mentions "counterfact", "mock server", "REPL", or "OpenAPI"
• Wants to test or develop against a mock API
• Needs to inspect or modify mock server state
• Wants to configure proxy vs. mock routing
• Needs to simulate API failures or edge cases
• Says things like:
  • "Add data to the mock"
  • "Change the mock state"
  • "Make the API return an error"
  • "Proxy this endpoint to the real server"
  • "What data is in the mock store?"
  • "Simulate a service failure"

Detecting Counterfact

To determine if Counterfact is running, check in this order:

1. Check for health endpoint (most reliable):

   GET http://localhost:3100/_counterfact/api/health

   If successful, Counterfact is running on port 3100.

2. Look for package.json:

   • Check if counterfact is in dependencies or devDependencies
   • Read scripts to find the port (e.g., --port 3000)

3. Check for routes directory:

   • Look for routes/ or api/routes/ directory
   • TypeScript/JavaScript files matching OpenAPI paths

4. Check for OpenAPI spec:

   • Files matching *.yaml, openapi.yaml, swagger.yaml
   • Look for openapi: or swagger: in content

5. Try alternate ports:

   • Port 3100 (default)
   • Port 3000 (common alternative)
   • Check environment variables or config files

Admin API Endpoints

All Admin API endpoints are prefixed with /_counterfact/api/

Health Check

Request:

GET /_counterfact/api/health

Response:

{
  "status": "ok",
  "port": 3100,
  "uptime": 123.45,
  "basePath": "/path/to/routes",
  "prefix": ""
}

Use when: Checking if server is running, getting server info.

List All Contexts

Request:

GET /_counterfact/api/contexts

Response:

{
  "success": true,
  "data": {
    "paths": ["/", "/pets", "/users"],
    "contexts": {
      "/": { "rootProperty": "value" },
      "/pets": { "pets": [...] },
      "/users": { "users": [...] }
    }
  }
}

Use when: Discovering what contexts exist, getting overview of all state.

Get Specific Context

Request:

GET /_counterfact/api/contexts/{path}

Example:

GET /_counterfact/api/contexts/pets

Response:

{
  "success": true,
  "data": {
    "path": "/pets",
    "context": {
      "pets": [
        { "id": 1, "name": "Fido" },
        { "id": 2, "name": "Whiskers" }
      ]
    }
  }
}

Use when: Inspecting state for a specific API path.

Update Context

Request:

POST /_counterfact/api/contexts/{path}
Content-Type: application/json

{
  "property": "newValue",
  "arrayProperty": [...]
}

Example:

POST /_counterfact/api/contexts/pets
Content-Type: application/json

{
  "pets": [
    { "id": 1, "name": "Fido" },
    { "id": 2, "name": "Whiskers" },
    { "id": 3, "name": "Rex" }
  ]
}

Response:

{
  "success": true,
  "message": "Context updated for path: /pets",
  "data": {
    "path": "/pets",
    "context": { "pets": [...] }
  }
}

Use when: Adding data, modifying state, simulating conditions.

Important: The update uses smart diffing - only changed properties are updated, preserving methods and other properties.

Get Full Configuration

Request:

GET /_counterfact/api/config

Response:

{
  "success": true,
  "data": {
    "alwaysFakeOptionals": false,
    "basePath": "/path/to/routes",
    "buildCache": false,
    "generate": { "routes": true, "types": true },
    "openApiPath": "/path/to/openapi.yaml",
    "port": 3100,
    "proxyUrl": "",
    "prefix": "",
    "startRepl": true,
    "startServer": true,
    "watch": { "routes": true, "types": true },
    "proxyPaths": []
  }
}

Use when: Getting full server configuration.

Get Proxy Configuration

Request:

GET /_counterfact/api/config/proxy

Response:

{
  "success": true,
  "data": {
    "proxyUrl": "https://api.example.com",
    "proxyPaths": [
      ["/api/users", true],
      ["/api/posts", false]
    ]
  }
}

Use when: Checking what paths are proxied vs. mocked.

Update Proxy Configuration

Request:

PATCH /_counterfact/api/config/proxy
Content-Type: application/json

{
  "proxyUrl": "https://api.example.com",
  "proxyPaths": [
    ["/api/users", true],
    ["/api/posts", false]
  ]
}

Response:

{
  "success": true,
  "message": "Proxy configuration updated",
  "data": {
    "proxyUrl": "https://api.example.com",
    "proxyPaths": [
      ["/api/users", true],
      ["/api/posts", false]
    ]
  }
}

Use when: Switching between mock and real API, testing integration.

Notes:

• proxyUrl is the base URL to proxy to
• proxyPaths is an array of [path, enabled] tuples
• Path of "" or "/" enables proxy globally
• Setting path true routes to real API, false uses mock

List All Routes

Request:

GET /_counterfact/api/routes

Response:

{
  "success": true,
  "data": {
    "routes": [
      {
        "path": "/pets",
        "methods": {
          "GET": true,
          "POST": true
        }
      },
      {
        "path": "/pets/{id}",
        "methods": {
          "GET": true,
          "PUT": true,
          "DELETE": true
        }
      }
    ]
  }
}

Use when: Discovering available endpoints, understanding API structure.

Common Usage Patterns

Pattern 1: Inspect Current State

User request: "What pets are in the store?"

Agent workflow:

1. GET /_counterfact/api/health
   → Confirm server running

2. GET /_counterfact/api/contexts/pets
   → Retrieve pets array

3. Present formatted list to user

Example response:

Currently in the pet store:
- ID 1: Fido
- ID 2: Whiskers

Pattern 2: Add Test Data

User request: "Add a new pet named Rex with ID 3"

Agent workflow:

1. GET /_counterfact/api/contexts/pets
   → Get current pets

2. Append new pet to array

3. POST /_counterfact/api/contexts/pets
   Body: { "pets": [...existingPets, newPet] }
   → Update context

4. Verify by GETting /pets endpoint
   → Confirm change visible in API

Pattern 3: Simulate Failure

User request: "Make the user service unavailable"

Agent workflow:

1. POST /_counterfact/api/contexts/users
   Body: { "serviceAvailable": false }
   → Set failure flag

2. Explain that route handlers should check this flag

3. Optionally: Test GET /users to verify error

Note: The route handler must be coded to check context.serviceAvailable. The skill sets the flag, but behavior depends on route implementation.