emuhealth 0.1.0 → 0.2.0

package/README.md

@@ -35,6 +35,8 @@ All services listen on IPv4 loopback (`127.0.0.1`) by default. No config file ne
 - **Linear** on `http://localhost:4012`
 - **Twilio** on `http://localhost:4013`
 
+Health and life science services use a fixed range starting at `http://localhost:4100`. Each health service keeps its port no matter which other services run or how many upstream services exist.
+
 Stripe webhooks configured with a secret include a `Stripe-Signature` header signed over the timestamp and raw request body.
 
 Slack event callbacks use `X-Slack-Request-Timestamp` and `X-Slack-Signature` when `slack.signing_secret` is configured. The signature is an HMAC-SHA256 over `v0:<timestamp>:<raw-body>`; configure the receiver with the same secret and verify against the unparsed request body. Existing event subscriptions remain unsigned when the secret is absent or empty.
@@ -82,13 +84,13 @@ try {
 }
 ```
 
-Use `defineConfig({ services: { acme: { emulator: acme }, github: { emulator: 'github' } } })` in `emulate.config.ts`. YAML/JSON entries accept local module paths and installed packages. `--config` selects a config explicitly; legacy flat configs and `--seed` remain supported. Node loads local TypeScript with path aliases and source locations without additional runtime dependencies. Node 26 supports erasable TypeScript only; compile enums and parameter properties to JavaScript before loading them. Node 24 also supports native TypeScript transforms.
+Use `defineConfig({ services: { acme: { emulator: acme }, github: { emulator: 'github' } } })` in `emuhealth.config.ts` (`emulate.config.ts` also works). YAML/JSON entries accept local module paths and installed packages. `--config` selects a config explicitly; legacy flat configs and `--seed` remain supported. Node loads local TypeScript with path aliases and source locations without additional runtime dependencies. Node 26 supports erasable TypeScript only; compile enums and parameter properties to JavaScript before loading them. Node 24 also supports native TypeScript transforms.
 
 Custom state uses your own record shapes and IDs. Seeds replace the complete initial state. Reset restores the captured seed; successful watch reloads create a new baseline and reset the run. With config auto-discovery, watch mode also detects recognized config files created after startup. Instances are independent. Persistence is opt-in, with versioned snapshots and no cross-process locking. Use `port: 0` for HTTP tests, or `listen: false` to test without opening a port. Custom reset and close are awaitable. Framework adapters keep root-relative custom redirects under the service mount while preserving custom HTML bodies.
 
 Streamed responses persist state changes when their bodies finish or are canceled. Reset and close cancel active streams before running cleanup. `c.header('Set-Cookie', value, { append: true })` retains cookies already set on the response. In a Next.js route, export `OPTIONS` from `createEmulateHandler` to forward preflight requests and custom OPTIONS handlers.
 
-See the [custom emulator guide](https://emulate.dev/docs/custom-emulators) and [complete inventory example](examples/custom-api) for validation, middleware, persistence, adapters, package sharing, and troubleshooting.
+See the [custom emulator guide](https://www.emuhealth.dev/docs/custom-emulators) and [complete inventory example](examples/custom-api) for validation, middleware, persistence, adapters, package sharing, and troubleshooting.
 
 ## CLI
 
@@ -122,7 +124,7 @@ npx emuhealth list
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `-p, --port` | `4000` | Base port (auto-increments per service) |
+| `-p, --port` | `4000` | Base port (auto-increments per service; health services start at base + 100) |
 | `--host` | `127.0.0.1` | Listening address; use `0.0.0.0` to allow network access |
 | `-s, --service` | all | Comma-separated services to enable |
 | `--seed` | auto-detect | Path to seed config (YAML or JSON) |
@@ -130,7 +132,7 @@ npx emuhealth list
 | `--portless` | off | Serve over HTTPS via portless (auto-registers aliases) |
 | `--generated-secrets-file` | none | Generate omitted service secrets and write them to a new owner-only JSON file |
 
-The port can also be set via `EMULATE_PORT` or `PORT` environment variables.
+The port can also be set via the `EMUHEALTH_PORT` or `PORT` environment variables. The upstream name `EMULATE_PORT` still works when `EMUHEALTH_PORT` is not set.
 
 For access from a container or another machine, use `npx emuhealth start --host 0.0.0.0`. Set `--base-url` to a URL reachable by those clients when using OAuth redirects or other advertised URLs.
 
@@ -158,13 +160,13 @@ If portless is not installed, emulate will prompt to install it (`npm i -g portl
 
 The `--portless` flag overwrites any existing portless aliases matching `*.emulate`. Aliases are removed automatically when emulate shuts down.
 
-For a custom base URL without portless (any reverse proxy), use `--base-url` or the `EMULATE_BASE_URL` env var:
+For a custom base URL without portless (any reverse proxy), use `--base-url` or the `EMUHEALTH_BASE_URL` env var (`EMULATE_BASE_URL` also works):
 
 ```bash
 npx emuhealth start --base-url "https://{service}.myproxy.test"
 ```
 
-The `PORTLESS_URL` env var is automatically set by the `portless` CLI wrapper when running a command through it (e.g. `portless github.emulate emuhealth start`), typically to a value like `https://{service}.emulate.localhost`. It supports `{service}` interpolation, just like `--base-url` and `EMULATE_BASE_URL`. When no explicit `baseUrl` is provided, it is used as a fallback.
+The `PORTLESS_URL` env var is automatically set by the `portless` CLI wrapper when running a command through it (e.g. `portless github.emulate emuhealth start`), typically to a value like `https://{service}.emulate.localhost`. It supports `{service}` interpolation, just like `--base-url` and `EMUHEALTH_BASE_URL`. When no explicit `baseUrl` is provided, it is used as a fallback.
 
 Per-service overrides are also supported in the seed config (these take highest priority over all other base URL sources):
 
@@ -258,7 +260,7 @@ afterAll(() => Promise.all([github.close(), vercel.close()]))
 | `port` | `4000` | Port for the HTTP server |
 | `hostname` | `127.0.0.1` | Listening address for built-in and custom emulators |
 | `seed` | none | Inline seed data (same shape as YAML config) |
-| `baseUrl` | none | Override advertised base URL. Per-service `baseUrl` in seed config takes highest priority, then this option, then `EMULATE_BASE_URL` env var (supports `{service}`), then `PORTLESS_URL` (supports `{service}`, automatically set by the `portless` CLI wrapper), then `http://localhost:<port>`. |
+| `baseUrl` | none | Override advertised base URL. Per-service `baseUrl` in seed config takes highest priority, then this option, then `EMUHEALTH_BASE_URL` env var (or `EMULATE_BASE_URL`, supports `{service}`), then `PORTLESS_URL` (supports `{service}`, automatically set by the `portless` CLI wrapper), then `http://localhost:<port>`. |
 
 Use `hostname: '0.0.0.0'` to allow connections from containers or other machines, and `baseUrl` to advertise a URL reachable by those clients.
 
@@ -273,7 +275,7 @@ Use `hostname: '0.0.0.0'` to allow connections from containers or other machines
 
 ## Configuration
 
-Configuration is optional. The CLI auto-detects config files in this order: `emulate.config.yaml` / `.yml`, `emulate.config.json`, `service-emulator.config.yaml` / `.yml`, `service-emulator.config.json`. Or pass `--seed <file>` explicitly. Run `npx emuhealth init` to generate a starter file.
+Configuration is optional. The CLI auto-detects config files in this order: `emuhealth.config.yaml` / `.yml`, `emuhealth.config.json`, then the upstream names `emulate.config.yaml` / `.yml`, `emulate.config.json`, `service-emulator.config.yaml` / `.yml`, `service-emulator.config.json`. An `emuhealth.config.*` file always wins over the upstream names. Or pass `--seed <file>` explicitly. Run `npx emuhealth init` to generate a starter file.
 
 ```yaml
 tokens:

package/dist/api.d.ts

@@ -249,8 +249,11 @@ declare function defineConfig<Definitions extends Record<string, EmulatorDefinit
     tokens?: EmulateConfig["tokens"];
 }): typeof config;
 
+declare const HEALTH_SERVICE_NAME_LIST: readonly [];
+type HealthServiceName = (typeof HEALTH_SERVICE_NAME_LIST)[number];
+
 declare const SERVICE_NAME_LIST: readonly ["vercel", "github", "google", "slack", "apple", "microsoft", "okta", "aws", "resend", "stripe", "mongoatlas", "clerk", "linear", "twilio"];
-type ServiceName = (typeof SERVICE_NAME_LIST)[number];
+type ServiceName = (typeof SERVICE_NAME_LIST)[number] | HealthServiceName;
 
 interface SeedConfig {
     tokens?: Record<string, {

package/dist/api.js

@@ -832,7 +832,7 @@ function createErrorHandler(documentationUrl) {
   };
 }
 var errorHandler = createErrorHandler();
-var isDebug = typeof process !== "undefined" && (process.env.DEBUG === "1" || process.env.DEBUG === "true" || process.env.EMULATE_DEBUG === "1");
+var isDebug = typeof process !== "undefined" && (process.env.DEBUG === "1" || process.env.DEBUG === "true" || process.env.EMULATE_DEBUG === "1" || process.env.EMUHEALTH_DEBUG === "1");
 function debug(label, ...args) {
   if (isDebug) {
     console.log(`[${label}]`, ...args);
@@ -1256,15 +1256,17 @@ body{
   .checkout-form-side{padding:32px 20px;}
 }
 `;
-var POWERED_BY = `<div class="powered-by">Powered by <a href="https://emulate.dev" target="_blank" rel="noopener">emulate</a></div>`;
+var PROJECT_URL = "https://www.emuhealth.dev";
+var REPO_URL = "https://github.com/emuhealth/emuhealth";
+var POWERED_BY = `<div class="powered-by">Powered by <a href="${PROJECT_URL}" target="_blank" rel="noopener">emuhealth</a></div>`;
 function emuBar(service) {
   const title = service ? `${escapeHtml(service)} Emulator` : "Emulator";
   return `<div class="emu-bar">
   <span class="emu-bar-title">${title}</span>
   <nav class="emu-bar-links">
-    <a href="https://github.com/vercel-labs/emulate/issues" target="_blank" rel="noopener"><span class="full">Report Issue</span><span class="short">Report</span></a>
-    <a href="https://github.com/vercel-labs/emulate" target="_blank" rel="noopener"><span class="full">Source Code</span><span class="short">Source</span></a>
-    <a href="https://emulate.dev" target="_blank" rel="noopener"><span class="full">Learn More</span><span class="short">Learn</span></a>
+    <a href="${REPO_URL}/issues" target="_blank" rel="noopener"><span class="full">Report Issue</span><span class="short">Report</span></a>
+    <a href="${REPO_URL}" target="_blank" rel="noopener"><span class="full">Source Code</span><span class="short">Source</span></a>
+    <a href="${PROJECT_URL}" target="_blank" rel="noopener"><span class="full">Learn More</span><span class="short">Learn</span></a>
   </nav>
 </div>`;
 }
@@ -1275,7 +1277,7 @@ function head(title) {
 <meta charset="utf-8"/>
 <meta name="viewport" content="width=device-width,initial-scale=1"/>
 <link rel="icon" href="/_emulate/favicon.ico"/>
-<title>${escapeHtml(title)} | emulate</title>
+<title>${escapeHtml(title)} | emuhealth</title>
 <style>${CSS}</style>
 </head>`;
 }
@@ -1937,13 +1939,41 @@ function defineConfig(config) {
   return config;
 }
 
+// src/registry-health.ts
+var HEALTH_SERVICE_NAME_LIST = [];
+var HEALTH_SERVICE_NAMES = HEALTH_SERVICE_NAME_LIST;
+var HEALTH_SERVICE_REGISTRY = {};
+var HEALTH_PORT_OFFSET = 100;
+function defaultServicePort(service, basePort, index, healthNames = HEALTH_SERVICE_NAMES) {
+  const healthIndex = healthNames.indexOf(service);
+  return healthIndex === -1 ? basePort + index : basePort + HEALTH_PORT_OFFSET + healthIndex;
+}
+
 // src/registry.ts
+var SERVICE_NAME_LIST = [
+  "vercel",
+  "github",
+  "google",
+  "slack",
+  "apple",
+  "microsoft",
+  "okta",
+  "aws",
+  "resend",
+  "stripe",
+  "mongoatlas",
+  "clerk",
+  "linear",
+  "twilio"
+];
+var SERVICE_NAMES = [...SERVICE_NAME_LIST, ...HEALTH_SERVICE_NAMES];
 var SERVICE_REGISTRY = {
+  ...HEALTH_SERVICE_REGISTRY,
   vercel: {
     label: "Vercel REST API emulator",
     endpoints: "projects, deployments, domains, env vars, users, teams, file uploads, protection bypass, blob storage",
     async load() {
-      const mod = await import("./dist-QJ24W3VN.js");
+      const mod = await import("./dist-YK2XJNH7.js");
       return { plugin: mod.vercelPlugin, seedFromConfig: mod.seedFromConfig };
     },
     defaultFallback(cfg) {
@@ -1970,7 +2000,7 @@ var SERVICE_REGISTRY = {
     label: "GitHub REST API emulator",
     endpoints: "users, repos, issues, PRs, comments, reviews, labels, milestones, branches, git data, orgs, teams, releases, webhooks, search, actions, checks, rate limit",
     async load() {
-      const mod = await import("./dist-7UXL7QGA.js");
+      const mod = await import("./dist-M5TIXC2F.js");
       return {
         plugin: mod.githubPlugin,
         seedFromConfig: mod.seedFromConfig,
@@ -2034,7 +2064,7 @@ var SERVICE_REGISTRY = {
     label: "Google OAuth 2.0 / OpenID Connect + Gmail, Calendar, and Drive emulator",
     endpoints: "OAuth authorize, token exchange, userinfo, RS256 OIDC discovery and JWKS, token revocation, Gmail messages/drafts/threads/labels/history/settings, Calendar discovery/lists/events/freebusy, Drive files/uploads",
     async load() {
-      const mod = await import("./dist-EESUF62H.js");
+      const mod = await import("./dist-575EVZLI.js");
       return { plugin: mod.googlePlugin, seedFromConfig: mod.seedFromConfig };
     },
     defaultFallback(cfg) {
@@ -2116,7 +2146,7 @@ var SERVICE_REGISTRY = {
     label: "Slack API emulator",
     endpoints: "auth, chat, conversations, users, profiles, presence, files, pins, bookmarks, views, reactions, team, OAuth, incoming webhooks, inspector",
     async load() {
-      const mod = await import("./dist-B5YXZCS3.js");
+      const mod = await import("./dist-IMIDQ6CJ.js");
       return { plugin: mod.slackPlugin, seedFromConfig: mod.seedFromConfig };
     },
     defaultFallback() {
@@ -2197,7 +2227,7 @@ var SERVICE_REGISTRY = {
     label: "Apple Sign In / OAuth emulator",
     endpoints: "OAuth authorize, token exchange, JWKS",
     async load() {
-      const mod = await import("./dist-SOYGDR4W.js");
+      const mod = await import("./dist-L3SNHIRB.js");
       return { plugin: mod.applePlugin, seedFromConfig: mod.seedFromConfig };
     },
     defaultFallback(cfg) {
@@ -2222,7 +2252,7 @@ var SERVICE_REGISTRY = {
     label: "Microsoft Entra ID OAuth 2.0 / OpenID Connect emulator",
     endpoints: "OAuth authorize, token exchange, userinfo, OIDC discovery, Graph /me, logout, token revocation",
     async load() {
-      const mod = await import("./dist-J2Q7BESS.js");
+      const mod = await import("./dist-ZGCIWJJM.js");
       return { plugin: mod.microsoftPlugin, seedFromConfig: mod.seedFromConfig };
     },
     defaultFallback(cfg) {
@@ -2247,7 +2277,7 @@ var SERVICE_REGISTRY = {
     label: "Okta OAuth 2.0 / OpenID Connect + management API emulator",
     endpoints: "OIDC discovery, JWKS, OAuth authorize/token/userinfo/introspect/revoke/logout, users, groups, apps, authorization servers",
     async load() {
-      const mod = await import("./dist-A2VVAQ3G.js");
+      const mod = await import("./dist-EUMN2OAH.js");
       return { plugin: mod.oktaPlugin, seedFromConfig: mod.seedFromConfig };
     },
     defaultFallback(cfg) {
@@ -2275,7 +2305,7 @@ var SERVICE_REGISTRY = {
     label: "AWS cloud service emulator",
     endpoints: "S3 (buckets, objects), SQS (queues, messages), Cognito (User Pools, OAuth, JWTs, Identity Pools), IAM (users, roles, access keys), STS (assume role, caller identity)",
     async load() {
-      const mod = await import("./dist-PLRHPEKZ.js");
+      const mod = await import("./dist-22OZW7MU.js");
       return { plugin: mod.awsPlugin, seedFromConfig: mod.seedFromConfig };
     },
     defaultFallback() {
@@ -2297,7 +2327,7 @@ var SERVICE_REGISTRY = {
     label: "Resend email API emulator",
     endpoints: "emails with idempotency, recipient restrictions, send attempts, domains, contacts, API keys, inbox UI",
     async load() {
-      const mod = await import("./dist-EGN5EUC3.js");
+      const mod = await import("./dist-B4K5JXTS.js");
       return { plugin: mod.resendPlugin, seedFromConfig: mod.seedFromConfig };
     },
     defaultFallback() {
@@ -2314,7 +2344,7 @@ var SERVICE_REGISTRY = {
     label: "Stripe payments emulator",
     endpoints: "customers, payment methods, customer sessions, payment intents, charges, products, prices, checkout sessions, webhooks",
     async load() {
-      const mod = await import("./dist-FJPSLFJD.js");
+      const mod = await import("./dist-KRJZAPPL.js");
       return { plugin: mod.stripePlugin, seedFromConfig: mod.seedFromConfig };
     },
     defaultFallback() {
@@ -2351,7 +2381,7 @@ var SERVICE_REGISTRY = {
     label: "Clerk authentication and user management emulator",
     endpoints: "OIDC discovery, JWKS, OAuth authorize/token/userinfo, users, email addresses, organizations, memberships, invitations, sessions",
     async load() {
-      const mod = await import("./dist-C6Y6IXLU.js");
+      const mod = await import("./dist-YMRASK5I.js");
       return { plugin: mod.clerkPlugin, seedFromConfig: mod.seedFromConfig };
     },
     defaultFallback(cfg) {
@@ -2390,7 +2420,7 @@ var SERVICE_REGISTRY = {
     label: "Linear GraphQL API emulator",
     endpoints: "GraphQL, OAuth, issues, teams, users, workflow states, comments, labels, projects, cycles, webhooks, agents, inspector",
     async load() {
-      const mod = await import("./dist-M5AWLPBU.js");
+      const mod = await import("./dist-ATXASBBA.js");
       return { plugin: mod.linearPlugin, seedFromConfig: mod.seedFromConfig };
     },
     defaultFallback(cfg) {
@@ -2455,7 +2485,7 @@ var SERVICE_REGISTRY = {
     label: "Twilio API emulator",
     endpoints: "accounts, API keys, phone numbers, Programmable Messaging, Messaging Services, Verify, Voice, webhooks, simulator, inspector",
     async load() {
-      const mod = await import("./dist-H6TJ2XTL.js");
+      const mod = await import("./dist-KAYD3L2O.js");
       return { plugin: mod.twilioPlugin, seedFromConfig: mod.seedFromConfig };
     },
     defaultFallback(cfg) {
@@ -2509,6 +2539,11 @@ var SERVICE_REGISTRY = {
   }
 };
 
+// src/env.ts
+function brandedEnv(name) {
+  return process.env[`EMUHEALTH_${name}`] || process.env[`EMULATE_${name}`] || void 0;
+}
+
 // src/base-url.ts
 function resolveBaseUrl(opts) {
   if (opts.seedBaseUrl) {
@@ -2517,7 +2552,7 @@ function resolveBaseUrl(opts) {
   if (opts.baseUrl) {
     return opts.baseUrl.replace(/\{service\}/g, opts.service);
   }
-  const envBaseUrl = process.env.EMULATE_BASE_URL;
+  const envBaseUrl = brandedEnv("BASE_URL");
   if (envBaseUrl) {
     return envBaseUrl.replace(/\{service\}/g, opts.service);
   }
@@ -2594,7 +2629,7 @@ function closeHttpServer(server) {
   });
 }
 async function createBuiltinEmulator(options) {
-  const { service, port = 4e3, seed: seedConfig } = options;
+  const { service, port = defaultServicePort(service, 4e3, 0), seed: seedConfig } = options;
   const entry = SERVICE_REGISTRY[service];
   if (!entry) {
     throw new Error(`Unknown service: ${service}`);