@warp-drive/holodeck 0.1.0-alpha.84 → 0.1.0-alpha.86

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@warp-drive/holodeck",
   "description": "⚡️ Simple, Fast HTTP Mocking for Tests",
-  "version": "0.1.0-alpha.84",
+  "version": "0.1.0-alpha.86",
   "license": "MIT",
   "author": "Chris Thoburn <runspired@users.noreply.github.com>",
   "repository": {
@@ -23,7 +23,6 @@
   },
   "type": "module",
   "files": [
-    "bin",
     "dist",
     "README.md",
     "LICENSE.md",
@@ -34,9 +33,9 @@
     "ensure-cert": "./server/ensure-cert.js"
   },
   "peerDependencies": {
-    "@warp-drive/utilities": "5.10.0-alpha.8",
-    "@warp-drive/legacy": "5.10.0-alpha.8",
-    "@warp-drive/core": "5.10.0-alpha.8"
+    "@warp-drive/utilities": "5.10.0-alpha.10",
+    "@warp-drive/legacy": "5.10.0-alpha.10",
+    "@warp-drive/core": "5.10.0-alpha.10"
   },
   "peerDependenciesMeta": {
     "@warp-drive/utilities": {
@@ -48,16 +47,17 @@
   },
   "devDependencies": {
     "@babel/core": "^7.29.7",
-    "@babel/plugin-transform-typescript": "^7.29.7",
+    "@babel/plugin-transform-typescript": "^7.29.9",
     "@babel/preset-env": "^7.29.7",
     "@babel/preset-typescript": "^7.29.7",
     "@babel/runtime": "^7.29.7",
-    "@warp-drive/utilities": "5.10.0-alpha.8",
-    "@warp-drive/legacy": "5.10.0-alpha.8",
-    "@warp-drive/core": "5.10.0-alpha.8",
-    "@warp-drive/internal-config": "5.10.0-alpha.8",
+    "@warp-drive/utilities": "5.10.0-alpha.10",
+    "@warp-drive/legacy": "5.10.0-alpha.10",
+    "@warp-drive/core": "5.10.0-alpha.10",
+    "@warp-drive/internal-config": "5.10.0-alpha.10",
+    "@types/node": "^26.6.2",
     "tsdown": "^0.23.0",
-    "typescript-7": "npm:typescript@7.1.0-dev.20260915.1"
+    "typescript-7": "npm:typescript@7.1.0-dev.20260920.1"
   },
   "exports": {
     ".": {
@@ -80,7 +80,7 @@
     }
   },
   "scripts": {
-    "check:types": "node ./node_modules/typescript-7/bin/tsc --noEmit",
+    "check:types": "node ./node_modules/typescript-7/bin/tsc --noEmit && node ./node_modules/typescript-7/bin/tsc --noEmit -p server",
     "build:pkg": "node node_modules/tsdown/dist/run.mjs",
     "sync": "echo \"syncing\"",
     "start": "node node_modules/tsdown/dist/run.mjs --watch"

package/server/ensure-cert.js

@@ -1,57 +1,83 @@
 #!/usr/bin/env node
 import { execSync } from 'node:child_process';
 import fs from 'node:fs';
+import { pathToFileURL } from 'node:url';
 import { homedir, userInfo } from 'os';
 import path from 'path';
 
-function getShellConfigFilePath() {
-  const shell = userInfo().shell;
-  switch (shell) {
-    case '/bin/zsh':
+const DEFAULT_CERT_PATH = path.join(homedir(), 'holodeck-localhost.pem');
+const DEFAULT_KEY_PATH = path.join(homedir(), 'holodeck-localhost-key.pem');
+
+const MKCERT_INSTALL_HINT = `
+mkcert was not found on your PATH. Holodeck serves over TLS and uses mkcert to
+issue a certificate for localhost.
+
+  macOS    brew install mkcert
+  Linux    sudo apt install libnss3-tools
+           then install mkcert from https://github.com/FiloSottile/mkcert/releases
+  Windows  choco install mkcert
+
+Install it and run this command again.
+`;
+
+/**
+ * `userInfo().shell` reports the login shell from the password database, which
+ * is not necessarily the shell the user is running. `$SHELL` is.
+ */
+function getShell() {
+  return process.env.SHELL || userInfo().shell;
+}
+
+/**
+ * Shells differ in where they read startup config from. A shell that isn't
+ * listed here still gets a working certificate, it just has to export the
+ * paths itself.
+ */
+function getShellConfigFilePath(shell) {
+  switch (path.basename(shell ?? '')) {
+    case 'zsh':
       return path.join(homedir(), '.zshrc');
-    case '/bin/bash':
+    case 'bash':
       return path.join(homedir(), '.bashrc');
-    case '/opt/homebrew/bin/fish':
-    case '/usr/local/bin/fish':
-    case '/bin/fish':
+    case 'fish':
       return path.join(homedir(), '.config', 'fish', 'config.fish');
     default:
-      throw Error(
-        `Unable to determine configuration file for shell: ${shell}. Manual SSL Cert Setup Required for Holodeck.`
-      );
+      return null;
   }
 }
 
-function main() {
-  let CERT_PATH = process.env.HOLODECK_SSL_CERT_PATH;
-  let KEY_PATH = process.env.HOLODECK_SSL_KEY_PATH;
-  const configFilePath = getShellConfigFilePath();
-
-  if (!CERT_PATH || !KEY_PATH) {
-    console.log(`Environment variables not found, updating the environment config file...\n`);
-
-    if (!CERT_PATH) {
-      CERT_PATH = path.join(homedir(), 'holodeck-localhost.pem');
-      process.env.HOLODECK_SSL_CERT_PATH = CERT_PATH;
-      execSync(`echo '\nexport HOLODECK_SSL_CERT_PATH="${CERT_PATH}"' >> ${configFilePath}`);
-      console.log(`Added HOLODECK_SSL_CERT_PATH to ${configFilePath}`);
-    }
-
-    if (!KEY_PATH) {
-      KEY_PATH = path.join(homedir(), 'holodeck-localhost-key.pem');
-      process.env.HOLODECK_SSL_KEY_PATH = KEY_PATH;
-      execSync(`echo '\nexport HOLODECK_SSL_KEY_PATH="${KEY_PATH}"' >> ${configFilePath}`);
-      console.log(`Added HOLODECK_SSL_KEY_PATH to ${configFilePath}`);
-    }
+function formatEnvLines(shell, vars) {
+  const isFish = path.basename(shell ?? '') === 'fish';
 
-    console.log(
-      `\n*** Please restart your terminal session to apply the changes or run \`source ${configFilePath}\`. ***\n`
-    );
+  return Object.entries(vars)
+    .map(([name, value]) => (isFish ? `set -gx ${name} "${value}"` : `export ${name}="${value}"`))
+    .join('\n');
+}
+
+function hasMkcert() {
+  try {
+    execSync('mkcert -version', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
   }
+}
+
+function main() {
+  if (!hasMkcert()) {
+    console.error(MKCERT_INSTALL_HINT);
+    process.exitCode = 1;
+    return;
+  }
+
+  const CERT_PATH = process.env.HOLODECK_SSL_CERT_PATH ?? DEFAULT_CERT_PATH;
+  const KEY_PATH = process.env.HOLODECK_SSL_KEY_PATH ?? DEFAULT_KEY_PATH;
 
   if (!fs.existsSync(CERT_PATH) || !fs.existsSync(KEY_PATH)) {
     console.log('SSL certificate or key not found, generating new ones...');
 
+    fs.mkdirSync(path.dirname(CERT_PATH), { recursive: true });
+    fs.mkdirSync(path.dirname(KEY_PATH), { recursive: true });
     execSync(`mkcert -install`);
     execSync(`mkcert -key-file ${KEY_PATH} -cert-file ${CERT_PATH} localhost`);
 
@@ -62,6 +88,34 @@ function main() {
 
   console.log(`Certificate path: ${CERT_PATH}`);
   console.log(`Key path: ${KEY_PATH}`);
+
+  if (process.env.HOLODECK_SSL_CERT_PATH && process.env.HOLODECK_SSL_KEY_PATH) {
+    return;
+  }
+
+  const shell = getShell();
+  const envLines = formatEnvLines(shell, {
+    HOLODECK_SSL_CERT_PATH: CERT_PATH,
+    HOLODECK_SSL_KEY_PATH: KEY_PATH,
+  });
+  const configFilePath = getShellConfigFilePath(shell);
+
+  if (!configFilePath) {
+    console.log(
+      `\nCould not determine a startup file for shell: ${shell ?? 'unknown'}.` +
+        `\nHolodeck falls back to ${DEFAULT_CERT_PATH} when the environment variables` +
+        `\nare unset, so the certificate above already works as it is.` +
+        `\nTo set them anyway, add the equivalent of these lines to your shell config:\n\n${envLines}\n`
+    );
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(configFilePath), { recursive: true });
+  fs.appendFileSync(configFilePath, `\n${envLines}\n`);
+  console.log(`\nAdded HOLODECK_SSL_CERT_PATH and HOLODECK_SSL_KEY_PATH to ${configFilePath}`);
+  console.log(`*** Restart your terminal session or run \`source ${configFilePath}\` to apply. ***\n`);
 }
 
-main();
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}

package/server/index.js

@@ -1,37 +1,20 @@
-/* global Bun */
-import path from 'path';
-const isBun = typeof Bun !== 'undefined';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
 let closeHandler = () => {};
 
 export default {
   async launchProgram(config = {}) {
     const projectRoot = process.cwd();
-    const name = await import(path.join(projectRoot, 'package.json'), { with: { type: 'json' } }).then(
-      (pkg) => pkg.name
-    );
+    const pkg = await import(pathToFileURL(path.join(projectRoot, 'package.json')).href, {
+      with: { type: 'json' },
+    });
+    const { name } = pkg.default ?? pkg;
     const options = { name, projectRoot, ...config };
 
-    if (!isBun) {
-      // @ts-expect-error
-      options.useWorker = config.useWorker ?? true;
-      const nodeImpl = await import('./node.js');
-      const program = await nodeImpl.launchProgram(options);
-      closeHandler = program.endProgram;
-      return program.config;
-    }
-
-    // if we are bun but should use node
-    if (!config.useBun) {
-      const compatImpl = await import('./compat-shim.js');
-      const program = await compatImpl.launchProgram(options);
-      closeHandler = program.endProgram;
-      return program.config;
-    }
-
-    // use bun
     // @ts-expect-error
     options.useWorker = config.useWorker ?? true;
-    const nodeImpl = await import('./bun.js');
+    const nodeImpl = await import('./node.js');
     const program = await nodeImpl.launchProgram(options);
     closeHandler = program.endProgram;
     return program.config;

package/server/node.js

@@ -2,10 +2,10 @@ import { serve } from '@hono/node-server';
 import { Hono } from 'hono';
 import { cors } from 'hono/cors';
 import { HTTPException } from 'hono/http-exception';
-import { logger } from 'hono/logger';
 import fs from 'node:fs';
 import { createSecureServer } from 'node:http2';
 import { Readable } from 'node:stream';
+import { pathToFileURL } from 'node:url';
 import { styleText } from 'node:util';
 import { Worker, threadId, parentPort } from 'node:worker_threads';
 import path from 'path';
@@ -25,7 +25,7 @@ async function replayRequest(context, cacheKey) {
   let metaJson;
   try {
     metaJson = JSON.parse(fs.readFileSync(`${cacheKey}.meta.json`, 'utf8'));
-  } catch (e) {
+  } catch {
     context.header('Content-Type', 'application/vnd.api+json');
     context.status(400);
     return context.body(
@@ -56,7 +56,7 @@ async function replayRequest(context, cacheKey) {
       metaJson.status !== 204 && metaJson.status < 500 ? Readable.toWeb(fs.createReadStream(bodyPath)) : '';
 
     const headers = new Headers(metaJson.headers || {});
-    const response = new Response(bodyInit, {
+    const response = new Response(/** @type {BodyInit} */ (bodyInit), {
       status: metaJson.status,
       statusText: metaJson.statusText,
       headers,
@@ -106,10 +106,10 @@ function createTestHandler(projectRoot) {
               {
                 status: '400',
                 code: 'MISSING_X_TEST_ID_HEADER',
-                title: 'Request to the http mock server is missing the `X-Test-Id` header',
+                title: 'Request to the http mock server is missing the `__xTestId` query parameter',
                 detail:
-                  "The `X-Test-Id` header is used to identify the test that is making the request to the mock server. This is used to ensure that the mock server is only used for the test that is currently running. If using @ember-data/request add import { MockServerHandler } from '@warp-drive/holodeck'; to your request handlers.",
-                source: { header: 'X-Test-Id' },
+                  'The `__xTestId` query parameter identifies the test making the request, so that the mock server only replays fixtures belonging to the test that is currently running. MockServerHandler adds it. Add `new MockServerHandler(this)` to your RequestManager chain ahead of Fetch, and check that the code under test issues its request through that chain rather than calling fetch directly.',
+                source: { parameter: '__xTestId' },
               },
             ],
           })
@@ -125,10 +125,10 @@ function createTestHandler(projectRoot) {
               {
                 status: '400',
                 code: 'MISSING_X_TEST_REQUEST_NUMBER_HEADER',
-                title: 'Request to the http mock server is missing the `X-Test-Request-Number` header',
+                title: 'Request to the http mock server is missing the `__xTestRequestNumber` query parameter',
                 detail:
-                  "The `X-Test-Request-Number` header is used to identify the request number for the current test. This is used to ensure that the mock server response is deterministic for the test that is currently running. If using @ember-data/request add import { MockServerHandler } from '@warp-drive/holodeck'; to your request handlers.",
-                source: { header: 'X-Test-Request-Number' },
+                  'The `__xTestRequestNumber` query parameter counts requests to the same method and url within a test, so that repeated requests replay their own fixtures in order. MockServerHandler adds it. Add `new MockServerHandler(this)` to your RequestManager chain ahead of Fetch, and check that the code under test issues its request through that chain rather than calling fetch directly.',
+                source: { parameter: '__xTestRequestNumber' },
               },
             ],
           })
@@ -295,7 +295,6 @@ async function createServer(options) {
 async function _createServer(options) {
   const { CERT, KEY } = await getCertInfo();
   const app = new Hono();
-  // app.use(logger());
 
   app.use(
     cors({
@@ -369,7 +368,7 @@ async function _createServer(options) {
 
 export async function launchProgram(config = {}) {
   const projectRoot = process.cwd();
-  const pkg = await import(path.join(projectRoot, 'package.json'), { with: { type: 'json' } });
+  const pkg = await import(pathToFileURL(path.join(projectRoot, 'package.json')).href, { with: { type: 'json' } });
   const { name } = pkg.default ?? pkg;
   if (!name) {
     throw new Error(`Package name not found in package.json`);
@@ -377,14 +376,14 @@ export async function launchProgram(config = {}) {
   const options = { name, projectRoot, ...config };
   console.log(
     styleText(
-      'grey',
+      'gray',
       `\n\t@${styleText('greenBright', 'warp-drive')}/${styleText(
         'magentaBright',
         'holodeck'
       )} 🌅\n\t=================================\n`
     ) +
       styleText(
-        'grey',
+        'gray',
         `\n\tHolodeck Access Granted\n\t\tprogram: ${styleText('magenta', name)}\n\t\tsettings: ${styleText(
           'green',
           JSON.stringify(config).split('\n').join(' ')
@@ -394,14 +393,14 @@ export async function launchProgram(config = {}) {
         )}@${styleText('yellow', process.version)}\n`
       )
   );
-  console.log(styleText('grey', `\n\tStarting Holodeck Subroutines`));
+  console.log(styleText('gray', `\n\tStarting Holodeck Subroutines`));
 
   const project = await createServer(options);
 
   async function shutdown() {
-    console.log(styleText('grey', `\n\tEnding Holodeck Subroutines`));
+    console.log(styleText('gray', `\n\tEnding Holodeck Subroutines`));
     project.server.close();
-    console.log(styleText('grey', `\n\tHolodeck program ended`));
+    console.log(styleText('gray', `\n\tHolodeck program ended`));
   }
 
   const endProgram = createCloseHandler(shutdown);

package/server/tsconfig.json

@@ -4,7 +4,8 @@
     "target": "ESNext",
     "module": "ESNext",
     "moduleResolution": "bundler",
-    "types": ["bun-types"],
+    "types": ["node"],
+    "strict": false,
     "allowJs": true,
     "checkJs": true,
     "noEmit": true

package/server/bun-worker.js

@@ -1,3 +0,0 @@
-import { startWorker } from './bun.js';
-
-startWorker();