Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
b75beb7
Upgrade to TypeScript 7
ctate Nov 5, 2026
617916f
Keep declarations current in dev
ctate Nov 6, 2026
9cb8659
Prepare v0.13.1 release (#353)
ctate Nov 8, 2026
8bfe994
Type-check with tsc-ts (#355)
ctate Nov 9, 2026
26a8fe7
Use `field-sizing` for the emulate chat input and tighten docs access…
ctate Nov 11, 2026
5bbb9c4
Refuse messages and calls from inactive Twilio accounts (#392)
ctate Nov 12, 2026
5cec11a
Align GitHub visibility, OAuth revocation, and token handling with th…
ctate Nov 12, 2026
6ccd8b7
Reject unknown Slack tokens in strict mode and support auth.revoke (#…
ctate Nov 12, 2026
03e096a
Align Okta sign-in, session revocation, and token handling with the r…
ctate Nov 12, 2026
2df53fc
Add opt-in Stripe API key checks (#390)
ctate Nov 12, 2026
f0452a4
Match Linear's webhook deliveries and Agent Interaction API (#394)
ctate Nov 14, 2026
d0158be
Add a MongoDB Atlas agent skill (#395)
ctate Nov 14, 2026
d995de5
Add STS web identity and KMS encryption to the AWS emulator (#398)
ctate Nov 14, 2026
9505d95
Accept markdown_text in Slack chat writes (#407)
ctate Nov 14, 2026
7732130
Match prefix wildcards in core route patterns (#408)
lahfir Nov 14, 2026
b230f29
Advertise the listening address in default base URLs (#409)
lahfir Nov 14, 2026
8024425
Detect a busy port before binding a specific address (#410)
lahfir Nov 14, 2026
ad7b0de
Add an external backend option to the AWS emulator (#411)
Railly Nov 16, 2026
13b5c70
Merge upstream vercel-labs/emulate main into github-only
byapparov Nov 16, 2026
9b8b376
fix: restore oxlint correctness rules, check the port before serving,…
byapparov Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -26,3 +26,4 @@ artifacts/
.superpowers/
packages/github-emulator/LICENSE
packages/github-emulator/THIRD_PARTY_NOTICES.md
.types/
55 changes: 55 additions & 0 deletions .oxlintrc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
{
"$schema": "./node_modules/oxlint/configuration_schema.json",
"plugins": [
"typescript"
],
"rules": {
"no-array-constructor": "error",
"no-unused-expressions": [
"error",
{
"allowShortCircuit": false,
"allowTaggedTemplates": false,
"allowTernary": false
}
],
"no-unused-vars": [
"warn",
{
"argsIgnorePattern": "^_",
"varsIgnorePattern": "^_"
}
],
"no-var": "error",
"prefer-const": [
"error",
{
"destructuring": "any",
"ignoreReadBeforeAssign": false
}
],
"prefer-rest-params": "error",
"prefer-spread": "error",
"typescript/ban-ts-comment": "error",
"typescript/no-duplicate-enum-values": "error",
"typescript/no-extra-non-null-assertion": "error",
"typescript/no-misused-new": "error",
"typescript/no-namespace": "error",
"typescript/no-non-null-asserted-optional-chain": "error",
"typescript/no-this-alias": "error",
"typescript/no-unnecessary-type-constraint": "error",
"typescript/no-unsafe-declaration-merging": "error",
"typescript/no-unsafe-function-type": "error",
"typescript/no-wrapper-object-types": "error",
"typescript/prefer-as-const": "error",
"typescript/prefer-namespace-keyword": "error",
"typescript/triple-slash-reference": "error"
},
"ignorePatterns": [
"**/dist/**",
"**/node_modules/**",
"**/.next/**",
"apps/**",
"examples/**"
]
}
17 changes: 14 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,22 @@
# Changelog

## 0.13.0
## 0.13.1

<!-- release:start -->

### Improvements

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 Changelog omits 0.13.1 auth behavior changes.

Suggested change
### Improvements
Add 0.13.1 entries for: strict GitHub-style token validation (default-on in the `github-emulator` package; `strict_scopes: false` in the seed opts out), OAuth code↔client binding, the new token/grant revocation endpoints, and private-repo 404 masking; document `strict_scopes` in the README seed-options section next to `GitHubSeedConfig`.
🤖 Fix with your agent
Fix this code review finding (aictrl-dev/github-emulator PR #11, CHANGELOG.md:7-15):

Problem: Changelog omits 0.13.1 auth behavior changes
Detail: The 0.13.1 entry documents only the toolchain upgrade, but this PR also ships user-observable auth behavior changes with no entry anywhere: (1) `createGitHubEmulator` now defaults `strict_scopes` to true, so tokens the emulator never issued get 401 Bad credentials instead of silently acting as the fallback user — a breaking change for existing consumers of the published package; (2) new `DELETE /applications/:client_id/{token,grant}` revocation endpoints; (3) OAuth authorization codes are now bound to the client_id they were issued to; (4) private repositories now answer 404 (not 401/403) to callers who cannot see them (orgs.test.ts expectation changed 403→404). The `strict_scopes` seed option is also absent from the docs. Users upgrading 0.13.0→0.13.1 get silent behavior flips.
Suggested fix: Add 0.13.1 entries for: strict GitHub-style token validation (default-on in the `github-emulator` package; `strict_scopes: false` in the seed opts out), OAuth code↔client binding, the new token/grant revocation endpoints, and private-repo 404 masking; document `strict_scopes` in the README seed-options section next to `GitHubSeedConfig`.

Implement the fix on the PR head branch and add a regression test that fails before the fix and passes after.
Why this matters

The 0.13.1 entry documents only the toolchain upgrade, but this PR also ships user-observable auth behavior changes with no entry anywhere: (1) createGitHubEmulator now defaults strict_scopes to true, so tokens the emulator never issued get 401 Bad credentials instead of silently acting as the fallback user — a breaking change for existing consumers of the published package; (2) new DELETE /applications/:client_id/{token,grant} revocation endpoints; (3) OAuth authorization codes are now bound to the client_id they were issued to; (4) private repositories now answer 404 (not 401/403) to callers who cannot see them (orgs.test.ts expectation changed 403→404). The strict_scopes seed option is also absent from the docs. Users upgrading 0.13.0→0.13.1 get silent behavior flips.

### Improvements

- Upgraded the build to **TypeScript 7**, with `tsc` emitting package declarations and `rolldown-plugin-dts` bundling the `emulate` API types. `@emulators/*` packages now ship one `.d.ts` file per module instead of a single bundled file; the `types` entry points and exported types are unchanged (#346)
- Kept **declarations current in watch mode** so `dev` builds re-emit types when type-only source files change (#352)


- Upgraded the build to **TypeScript 7**, with `tsc` emitting package declarations and `rolldown-plugin-dts` bundling the `emulate` API types. `@emulators/*` packages now ship one `.d.ts` file per module instead of a single bundled file; the `types` entry points and exported types are unchanged (#346)
- Kept **declarations current in watch mode** so `dev` builds re-emit types when type-only source files change (#352)

### Contributors

- @ctate

<!-- release:end -->

## 0.13.0

### New Features

- Added **local MCP server** with `npx emulate mcp` so agents can list services, create configurations, and start or stop emulators through shared CLI tools (#331)
Expand All @@ -16,8 +29,6 @@

- @lahfir

<!-- release:end -->

## 0.12.3

### New Features
Expand Down
18 changes: 0 additions & 18 deletions eslint.config.mjs

This file was deleted.

9 changes: 4 additions & 5 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
"build": "node scripts/build.mjs",
"test": "pnpm -r test",
"type-check": "pnpm -r type-check",
"type-check:tsc": "pnpm -r type-check:tsc",
"lint": "pnpm -r lint",
"format": "prettier --write \"**/*.{ts,tsx}\"",
"format:check": "prettier --check \"**/*.{ts,tsx}\"",
Expand All @@ -18,12 +19,10 @@
},
"devDependencies": {
"@types/node": "^22",
"eslint": "^9.39.4",
"eslint-config-prettier": "^10.1.8",
"playwright": "^1.64.1",
"oxlint": "^1.91.0",
"prettier": "^3.8.1",
"typescript": "^5.7",
"typescript-eslint": "^8.58.0",
"playwright": "^1.64.1",
"typescript": "^7.0.2",
"vitest": "^4.1.0"
},
"packageManager": "pnpm@11.2.2",
Expand Down
12 changes: 7 additions & 5 deletions packages/@emulators/core/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@emulators/core",
"version": "0.13.0",
"version": "0.13.1",
"license": "Apache-2.0",
"type": "module",
"main": "./dist/index.js",
Expand Down Expand Up @@ -31,19 +31,21 @@
],
"scripts": {
"build": "tsup --clean",
"dev": "tsup --watch",
"dev": "tsup --watch src",
"test": "vitest run",
"clean": "rm -rf dist .turbo",
"type-check": "tsc --noEmit",
"lint": "eslint src",
"type-check": "tsc-ts --noEmit",
"type-check:tsc": "tsc --noEmit",
"lint": "oxlint src",
"prepack": "node ../../../scripts/prepare-package.mjs"
},
"dependencies": {
"jose": "^6.2.2"
},
"devDependencies": {
"tsc-ts": "0.1.3",
"tsup": "^8",
"typescript": "^5.7",
"typescript": "^7.0.2",
"vitest": "^4.1.0"
}
}
86 changes: 84 additions & 2 deletions packages/@emulators/core/src/__tests__/http.test.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import { describe, expect, it } from "vitest";
import { once } from "node:events";
import type { AddressInfo } from "node:net";
import { Hono, cors, serve } from "../http.js";
import { createServer, type AddressInfo, type Server } from "node:net";
import { Hono, assertPortFree, cors, serve } from "../http.js";

describe("HTTP listener", () => {
it.each([
Expand Down Expand Up @@ -80,6 +80,36 @@ describe("internal http layer", () => {
expect(res.headers.get("X-Handler")).toBe("get");
});

it.each([
{ pattern: "/auth/*", hits: ["/auth", "/auth/login", "/auth/a/b"], misses: ["/authx", "/other"] },
{ pattern: "/a/:id/*", hits: ["/a/1", "/a/1/z", "/a/1/z/w"], misses: ["/a", "/b/1/z"] },
{ pattern: "/m/*/end", hits: ["/m/x/end"], misses: ["/m/end", "/m/x/y/end"] },
{ pattern: "/files*", hits: ["/files*"], misses: ["/filesx", "/files"] },
])("matches wildcard pattern $pattern", async ({ pattern, hits, misses }) => {
const app = new Hono();
app.get(pattern, (c) => c.text("hit"));
for (const path of hits) expect(await (await app.request(path)).text()).toBe("hit");
for (const path of misses) expect((await app.request(path)).status).toBe(404);
});

it("runs prefix middleware under its path only", async () => {
const app = new Hono();
app.use("/auth/*", async (c, next) => {
c.header("x-guard", "1");
await next();
});
app.get("/*", (c) => c.text("ok"));

expect((await app.request("/auth/login")).headers.get("x-guard")).toBe("1");
expect((await app.request("/public")).headers.get("x-guard")).toBeNull();
});

it("detects duplicate wildcard routes in strict mode", () => {
const app = new Hono({ strictRoutes: true });
app.get("/files/*", (c) => c.text("a"));
expect(() => app.get("/files/*", (c) => c.text("b"))).toThrow(/Duplicate route/);
});

it("handles CORS preflight requests", async () => {
const app = new Hono();
app.use("*", cors({ allowMethods: ["GET"], allowHeaders: ["x-test"], maxAge: 60 }));
Expand All @@ -93,4 +123,56 @@ describe("internal http layer", () => {
expect(res.headers.get("Access-Control-Allow-Headers")).toBe("x-test");
expect(res.headers.get("Access-Control-Max-Age")).toBe("60");
});

async function hold(host?: string): Promise<Server | undefined> {
const holder = createServer();
holder.listen(0, host);
try {
await once(holder, "listening");
return holder;
} catch {
return undefined;
}
}

it("reports a port that a wildcard listener holds", async () => {
const holder = (await hold())!;
const { port } = holder.address() as AddressInfo;
try {
await expect(assertPortFree("127.0.0.1", port)).rejects.toMatchObject({ code: "EADDRINUSE" });
} finally {
holder.close();
}
});

it("accepts a port that only another address holds", async () => {
const holder = await hold("::1");
if (!holder) return;
const { port } = holder.address() as AddressInfo;
try {
await expect(assertPortFree("127.0.0.1", port)).resolves.toBeUndefined();
} finally {
holder.close();
}
});

it("leaves an invalid port for listen to report", async () => {
await expect(assertPortFree("127.0.0.1", 70000)).resolves.toBeUndefined();
expect(() => serve({ fetch: () => new Response("ready"), port: 70000 })).toThrow();
});

it("accepts a connection made right after serve returns", async () => {
const holder = (await hold("127.0.0.1"))!;
const { port } = holder.address() as AddressInfo;
await new Promise((resolve) => holder.close(resolve));
const server = serve({ fetch: () => new Response("ready"), port });
try {
expect(await (await fetch(`http://127.0.0.1:${port}`)).text()).toBe("ready");
} finally {
await new Promise<void>((resolve) => {
server.close(() => resolve());
server.closeAllConnections();
});
}
});
});
63 changes: 55 additions & 8 deletions packages/@emulators/core/src/http.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@
* Copyright (c) 2021 - present, Yusuke Wada and Hono contributors
* MIT license: see THIRD_PARTY_NOTICES.md in the repository and npm packages.
*/
import { lookup } from "node:dns/promises";
import { connect, isIP } from "node:net";
import { createServer as createNodeServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";

type BodyInit = ConstructorParameters<typeof Response>[0];
Expand Down Expand Up @@ -443,40 +445,85 @@ export function serve(options: ServeOptions): Server {
return server;
}

/**
* Rejects with an EADDRINUSE error when something already accepts connections on the address a listener is about to
* bind. Await it before `serve`: macOS lets a specific address bind a port another process holds on the wildcard
* address. The other process sees one short connection.
*/
export async function assertPortFree(hostname: string | undefined, port: number): Promise<void> {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 assertPortFree probes only one resolved address.

Suggested change
export async function assertPortFree(hostname: string | undefined, port: number): Promise<void> {
Resolve with `lookup(host, { all: true })` and probe every returned address (or at minimum both 127.0.0.1 and ::1 for localhost-style names); throw EADDRINUSE if any of them accepts a connection.
🤖 Fix with your agent
Fix this code review finding (aictrl-dev/github-emulator PR #11, packages/@emulators/core/src/http.ts:453-462):

Problem: assertPortFree probes only one resolved address
Detail: assertPortFree resolves the hostname once and probes a single address. For 'localhost', dns.lookup often returns ::1 first while another process holds the port on 127.0.0.1: the probe to [::1] fails, the function resolves, serve() binds the IPv6 address, and traffic sent to 127.0.0.1:port silently reaches the foreign listener — exactly the split-listener condition the helper was added to prevent. Same gap for hostnames with multiple A records. Only affects callers passing a DNS hostname (createGitHubEmulator defaults to the literal 127.0.0.1, which skips lookup).
Suggested fix: Resolve with `lookup(host, { all: true })` and probe every returned address (or at minimum both 127.0.0.1 and ::1 for localhost-style names); throw EADDRINUSE if any of them accepts a connection.

Implement the fix on the PR head branch and add a regression test that fails before the fix and passes after.
Why this matters

assertPortFree resolves the hostname once and probes a single address. For 'localhost', dns.lookup often returns ::1 first while another process holds the port on 127.0.0.1: the probe to [::1] fails, the function resolves, serve() binds the IPv6 address, and traffic sent to 127.0.0.1:port silently reaches the foreign listener — exactly the split-listener condition the helper was added to prevent. Same gap for hostnames with multiple A records. Only affects callers passing a DNS hostname (createGitHubEmulator defaults to the literal 127.0.0.1, which skips lookup).

export async function assertPortFree(hostname: string | undefined, port: number): Promise<void> {
  const host = hostname ?? "127.0.0.1";
  if (port === 0 || host === "0.0.0.0" || host === "::") return;
  const address = isIP(host)
    ? host
    : await lookup(host).then(
        (r) => r.address,
        () => undefined,
      );
  if (!address) return;
  const taken = await new Promise<boolean>((resolve) => {
    try {
      const socket = connect({ host: address, port, timeout: 300 });

const host = hostname ?? "127.0.0.1";
if (port === 0 || host === "0.0.0.0" || host === "::") return;
const address = isIP(host)
? host
: await lookup(host).then(
(r) => r.address,
() => undefined,
);
if (!address) return;
const taken = await new Promise<boolean>((resolve) => {
try {
const socket = connect({ host: address, port, timeout: 300 });
const settle = (value: boolean) => {
socket.destroy();
resolve(value);
};
socket.once("connect", () => settle(true));
socket.once("timeout", () => settle(false));
socket.once("error", () => settle(false));
} catch {
resolve(false);
}
});
if (!taken) return;
throw Object.assign(new Error(`listen EADDRINUSE: address already in use ${address}:${port}`), {
code: "EADDRINUSE",
errno: -48,
syscall: "listen",
address,
port,
});
}

function compilePath(pattern: string): CompiledPath {
if (pattern === "*" || pattern === "/*") {
return { pattern, regex: /^.*$/, paramNames: [] };
}

const prefix = pattern.endsWith("/*");
const body = prefix ? pattern.slice(0, -2) : pattern;
const paramNames: string[] = [];
let source = "^";
for (let i = 0; i < pattern.length; i++) {
const char = pattern[i];
for (let i = 0; i < body.length; i++) {
const char = body[i];
if (char === "*" && body[i - 1] === "/" && (i + 1 === body.length || body[i + 1] === "/")) {
source += "[^/]+";
continue;
}
if (char !== ":") {
source += escapeRegex(char);
continue;
}

let name = "";
i++;
while (i < pattern.length && /[A-Za-z0-9_]/.test(pattern[i])) {
name += pattern[i];
while (i < body.length && /[A-Za-z0-9_]/.test(body[i])) {
name += body[i];
i++;
}
i--;
paramNames.push(name);

if (pattern[i + 1] === "{") {
const close = pattern.indexOf("}", i + 2);
if (body[i + 1] === "{") {
const close = body.indexOf("}", i + 2);
if (close < 0) throw new Error(`Invalid route pattern: ${pattern}`);
const expr = pattern.slice(i + 2, close);
const expr = body.slice(i + 2, close);
source += `(${expr})`;
i = close;
} else {
source += "([^/]+)";
}
}
source += "$";
source += prefix ? "(?:/.*)?$" : "$";
return { pattern, regex: new RegExp(source), paramNames };
}

Expand Down
1 change: 1 addition & 0 deletions packages/@emulators/core/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ export {
HonoRequest,
cors,
serve,
assertPortFree,
type ContentfulStatusCode,
type CorsOptions,
type ErrorHandler,
Expand Down
10 changes: 10 additions & 0 deletions packages/@emulators/core/tsconfig.build.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{
"extends": "./tsconfig.json",
"compilerOptions": {
"rootDir": "./src",
"outDir": "./dist",
"emitDeclarationOnly": true,
"declarationMap": false
},
"exclude": ["node_modules", "dist", "src/**/*.test.ts", "src/**/__tests__/**"]
}
Loading
Loading