jam 0.8.1 → 0.9.0

package/README.md

@@ -1,60 +1,62 @@
 # jam
 
-Jam is an application server for isolated JavaScript. It runs JavaScript (and TypeScript) per request with isolated execution contexts, inspired by the PHP-FPM model.
-
-## Install
-
-```sh
-npm install -g jam
-jam --help
-```
+`jam` is an application server for isolated JavaScript. It runs JavaScript (and TypeScript) per request with isolated execution contexts, inspired by the PHP-FPM model.
 
 ## Usage
 
-Create a `scripts/app.ts` file:
-
-```ts
-export default {
-  fetch(request: Request): Response {
-    return new Response("Hello from Jam");
-  }
-};
-```
-
-Start Jam, pointing it at the scripts folder:
-
-```sh
-jam ./scripts
+```bash
+jam [flags] [scripts-dir]
 ```
 
-Now make a request. Jam maps `/app` to `app.ts`.
-
-```sh
-curl http://localhost:3000/app
+Run `jam --help` for all options:
+
+```text
+Options:
+  --port <port>                            TCP port to listen on.
+  --host <host>                            Host or IP address to bind the TCP server to.
+  --unix <path>                            Unix socket path to listen on instead of TCP.
+  --php                                    Enable PHP-style globals such as $_GET, $_POST, and $_SERVER.
+  --public <dir>                           Directory for static files (checked before script routes).
+  --access-log                             Enable per-request access log output.
+  --config <path>                          Path to jamconfig.json (default: ./jamconfig.json).
+  --env <KEY=VALUE>                        Set an env var for scripts; include multiple times.
+  --log <path|->                           Log destination ('-' for stdout, otherwise a file path).
+  --log-level <error|warning|info|debug>   Minimum log level to emit (default: info).
+  --tls-cert <path>                        Path to TLS certificate PEM file.
+  --tls-key <path>                         Path to TLS private key PEM file.
+  --timeout-ms <ms>                        Maximum script execution time in milliseconds.
+  --request-max-body-bytes <bytes>         Maximum allowed request body size in bytes.
+  --request-max-header-bytes <bytes>       Maximum allowed request header size in bytes.
+  --workers <count>                        Worker pool size (0 uses automatic sizing).
+  --worker-memory-mb <mb>                  Per-worker memory limit in MB.
+  --worker-max-requests <count>            Recycle a worker after this many requests.
+  --mode <value>                           Runtime mode string (commonly production or development).
+  --error-page-404 <path>                  Path to a custom 404 error page.
+  --error-page-500 <path>                  Path to a custom 500 error page.
+  --help                                   Print this help message and exit.
+  --version                                Print version and exit.
+
+Examples:
+  jam
+  jam --port 3000
+  jam ./app
+  jam --php --public ./public ./app
 ```
 
-Edit the file and make the same request again. The next request runs the updated script immediately, with no rebuilds or restarts.
-
-## Documentation
-
-To learn more, see [the documentation](https://github.com/mjackson/jam/tree/main/docs).
-
-## How platform binaries are downloaded
-
-The `jam` package uses platform-specific optional dependencies. During install, npm picks the matching package for your OS/CPU target:
-
-- [`jam-darwin-arm64`](https://www.npmjs.com/package/jam-darwin-arm64)
-- [`jam-darwin-x64`](https://www.npmjs.com/package/jam-darwin-x64)
-- [`jam-linux-x64`](https://www.npmjs.com/package/jam-linux-x64)
-- [`jam-linux-arm64`](https://www.npmjs.com/package/jam-linux-arm64)
-
-Current support is macOS (`darwin`) and Linux glibc builds. Linux musl and Windows targets are not published yet.
+Warning and error messages are written to stderr, while info/debug messages are written to stdout when logging to stdout.
+When stderr is an interactive terminal, warning output is yellow and error output is red.
+Set `NO_COLOR` in the environment to force no colors.
 
-## Environment overrides
+## Development
 
-- `JAM_LIBC=glibc|musl`: override Linux libc detection.
-- `JAM_BINARY_PATH=<path>`: run a specific local binary instead of the optional dependency binary.
+`jam` has two entry points with different roles:
 
-## Local development
+- `bin/jam.js`: Node-facing dispatch shim for the npm package.
+  - This is what `npx jam` and `npm/yarn/pnpm` bin resolution executes.
+  - It picks the correct platform package (`jam-darwin-arm64`, `jam-darwin-x64`, `jam-linux-arm64`, `jam-linux-x64`), installs it if needed, and forwards execution to its binary.
+- `src/entry.ts`: Bun runtime CLI entrypoint.
+  - This is what gets compiled into each platform binary.
+  - It should remain minimal and primarily call into `main` from `src/main.ts`.
+  - CI and release scripts build it for each target.
 
-Install dependencies with optional dependencies enabled so the matching platform package is available.
+The fallback path used in `bin/jam.js` (`../src/entry.ts`) is for local development when running from a checked out repo and the platform package binary is unavailable.

package/bin/jam.js

@@ -1,29 +1,180 @@
 #!/usr/bin/env node
-"use strict";
 
-let { spawnSync } = require("node:child_process");
+// This is the user-facing Node entrypoint for the npm `jam` package.
+// `npx jam` and the package binary in `package.json` resolve here first.
+//
+// It exists because the published `jam` package is a tiny bootstrap layer:
+// it detects the host platform, resolves the corresponding platform package
+// (`jam-darwin-arm64`, `jam-darwin-x64`, `jam-linux-arm64`, `jam-linux-x64`),
+// and executes the native Jam binary shipped by that package.
+//
+// If the platform package is not installed yet, this shim tries to install it
+// on demand via `npm install <platform-package>@<version> --no-save`.
+// If Bun is available in a local repo checkout and no platform package is
+// present, it falls back to running `src/main.ts` directly for development.
+//
+// `src/entry.ts` is the Bun source entrypoint used by platform package builds;
+// this file (`jam.js`) is the runtime dispatcher that selects and runs them.
 
-let { resolveBinaryPath } = require("../lib/resolve-binary");
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+let require = createRequire(import.meta.url);
+let THIS_FILE = fileURLToPath(import.meta.url);
+let THIS_DIR = path.dirname(THIS_FILE);
+let PACKAGE_DIR = path.resolve(THIS_DIR, "..");
+let PACKAGE_JSON = path.join(PACKAGE_DIR, "package.json");
+
+function resolvePlatformPackageName() {
+  let key = `${process.platform}-${process.arch}`;
+
+  if (key === "darwin-arm64") {
+    return "jam-darwin-arm64";
+  }
+
+  if (key === "darwin-x64") {
+    return "jam-darwin-x64";
+  }
+
+  if (key === "linux-arm64") {
+    return "jam-linux-arm64";
+  }
+
+  if (key === "linux-x64") {
+    return "jam-linux-x64";
+  }
+
+  return "";
+}
+
+function runProcess(command, args, options) {
+  let result = spawnSync(command, args, {
+    stdio: "inherit",
+    ...options
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  if (typeof result.status === "number") {
+    return result.status;
+  }
+
+  return 1;
+}
+
+function resolvePlatformBinary(packageName) {
+  let packageJsonPath = require.resolve(`${packageName}/package.json`);
+  return path.join(path.dirname(packageJsonPath), "bin", "jam");
+}
+
+function getMainPackageVersion() {
+  let packageJson = JSON.parse(fs.readFileSync(PACKAGE_JSON, "utf8"));
+  return packageJson.version;
+}
+
+function installPlatformPackage(packageName) {
+  let version = getMainPackageVersion();
+  let packageSpec = `${packageName}@${version}`;
+
+  let npmHasInstall = false;
+  let npmVersionResult = spawnSync("npm", ["--version"], {
+    stdio: "ignore"
+  });
+
+  if (
+    typeof npmVersionResult.status === "number" &&
+    npmVersionResult.status === 0
+  ) {
+    npmHasInstall = true;
+  }
+
+  if (!npmHasInstall) {
+    throw new Error(
+      "npm is required to install the platform package automatically."
+    );
+  }
+
+  let result = runProcess(
+    "npm",
+    ["install", packageSpec, "--no-save", "--no-audit", "--no-fund"],
+    {
+      cwd: PACKAGE_DIR
+    }
+  );
+
+  if (result !== 0) {
+    throw new Error(`npm install failed for ${packageSpec} (status: ${result}).`);
+  }
+}
+
+function runPlatformBinary(packageName, args) {
+  let binaryPath = resolvePlatformBinary(packageName);
+  return runProcess(binaryPath, args);
+}
+
+function maybeRunDevFallback(args) {
+  let sourceEntrypoint = path.resolve(THIS_DIR, "../src/entry.ts");
+  if (!fs.existsSync(sourceEntrypoint)) {
+    return false;
+  }
+
+  runProcess("bun", [sourceEntrypoint, ...args]);
+  return true;
+}
 
 function main() {
-  try {
-    let binaryPath = resolveBinaryPath();
-    let result = spawnSync(binaryPath, process.argv.slice(2), {
-      stdio: "inherit",
-    });
+  let packageName = resolvePlatformPackageName();
+
+  if (!packageName) {
+    process.stderr.write(
+      `[jam] Unsupported platform: ${process.platform}-${process.arch}. ` +
+      "Supported platforms: darwin-arm64, darwin-x64, linux-arm64, linux-x64.\n"
+    );
+    process.exit(1);
+  }
 
-    if (result.error) throw result.error;
+  let args = process.argv.slice(2);
 
-    if (typeof result.status === "number") {
-      process.exit(result.status);
+  try {
+    let exitCode = runPlatformBinary(packageName, args);
+    process.exit(exitCode);
+  } catch (error) {
+    let installError = null;
+    if (
+      error instanceof Error &&
+      error.message.includes("Could not resolve") &&
+      error.message.includes(`${packageName}/package.json`)
+    ) {
+      try {
+        process.stderr.write(
+          `[jam] Installing platform package ${packageName}...\n`
+        );
+        installPlatformPackage(packageName);
+        let exitCode = runPlatformBinary(packageName, args);
+        process.exit(exitCode);
+      } catch (secondError) {
+        installError = secondError;
+      }
     }
 
-    if (result.signal) {
-      process.kill(process.pid, result.signal);
+    if (installError === null && maybeRunDevFallback(args)) {
       return;
     }
-  } catch (error) {
-    console.error(`[jam] ${error.message}`);
+
+    let message = installError instanceof Error
+      ? installError.message
+      : error instanceof Error
+        ? error.message
+        : String(error);
+    process.stderr.write(
+      `[jam] Could not find platform binary package ${packageName}. ` +
+      `Try reinstalling dependencies. (${message})\n`
+    );
     process.exit(1);
   }
 }

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "jam",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "An application server for isolated JavaScript",
   "license": "MIT",
-  "type": "commonjs",
+  "type": "module",
+  "types": "types/index.d.ts",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mjackson/jam.git",
@@ -16,21 +17,39 @@
   "bin": {
     "jam": "bin/jam.js"
   },
-  "optionalDependencies": {
-    "jam-darwin-arm64": "0.8.1",
-    "jam-darwin-x64": "0.8.1",
-    "jam-linux-x64": "0.8.1",
-    "jam-linux-arm64": "0.8.1"
-  },
   "files": [
-    "bin",
-    "lib",
-    "README.md"
+    "bin/jam.js",
+    "README.md",
+    "types/**"
   ],
+  "publishConfig": {
+    "executableFiles": [
+      "bin/jam.js"
+    ]
+  },
+  "optionalDependencies": {
+    "jam-darwin-arm64": "0.9.0",
+    "jam-darwin-x64": "0.9.0",
+    "jam-linux-arm64": "0.9.0",
+    "jam-linux-x64": "0.9.0"
+  },
+  "dependencies": {
+    "@jridgewell/trace-mapping": "^0.3.31",
+    "typescript": "^5.6.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.31",
+    "bun-types": "^1.2.8"
+  },
   "engines": {
-    "node": ">=18"
+    "bun": ">=1.2"
   },
   "scripts": {
-    "test": "node test/platform.test.js && node test/resolve-optional-package.test.js && node test/platform-package-manifests.test.js"
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "bun run test:unit && bun run test:integration",
+    "test:unit": "bun test ./src/**/*.test.ts",
+    "test:integration": "bun test ./test/*.test.ts",
+    "build:bin": "bun build ./src/entry.ts --compile --outfile ./dist/jam"
   }
 }

package/types/index.d.ts

@@ -0,0 +1 @@
+/// <reference path="./jam/index.d.ts" />

package/types/jam/index.d.ts

@@ -0,0 +1,96 @@
+declare module "jam:template" {
+  export interface RenderTemplateResult {
+    body: string;
+    status: number;
+    headers: Headers;
+  }
+
+  export class TemplateRuntimeError extends Error {
+    templatePath: string;
+    constructor(templatePath: string, message: string);
+  }
+
+  export class TemplateCompileError extends Error {
+    constructor(templatePath: string, message: string);
+  }
+
+  export class TemplateSyntaxError extends Error {
+    line: number;
+    column: number;
+    constructor(templatePath: string, message: string, line: number, column: number);
+  }
+
+  export class TemplateCompiler {
+    constructor(maxEntries?: number);
+    renderTemplate(
+      templatePath: string,
+      scriptRoot: string,
+      runtimeContext: Record<string, unknown>,
+      request: Request
+    ): Promise<RenderTemplateResult>;
+    getCacheSize(): number;
+  }
+
+  export function renderTemplate(
+    templatePath: string,
+    scriptRoot: string,
+    runtimeContext: Record<string, unknown>,
+    request: Request
+  ): Promise<RenderTemplateResult>;
+}
+
+declare module "jam:test" {
+  export class AssertionError extends Error {
+    actual: unknown;
+    expected: unknown;
+    operator: string;
+  }
+
+  export namespace assert {
+    function ok(value: unknown, message?: string): asserts value;
+    function equal(actual: unknown, expected: unknown, message?: string): void;
+    function deepEqual(actual: unknown, expected: unknown, message?: string): void;
+  }
+
+  export interface SpyCall {
+    args: unknown[];
+    thisValue: unknown;
+  }
+
+  export interface Spy {
+    calls: SpyCall[];
+    restore(): void;
+  }
+
+  export function mock(
+    target: object,
+    methodName: string,
+    implementation: (...args: unknown[]) => unknown
+  ): () => void;
+
+  export function spyOn(target: object, methodName: string): Spy;
+
+  export function restoreAll(): void;
+}
+
+declare type JamPhpFile = {
+  name: string;
+  type: string;
+  tmp_name: string;
+  error: number;
+  size: number;
+};
+
+declare type JamPhpFiles = Record<string, JamPhpFile | JamPhpFile[]>;
+
+declare type JamPhpServer = {
+  REQUEST_METHOD?: string;
+  REQUEST_URI?: string;
+  [key: string]: string | undefined;
+};
+
+declare const $_GET: Record<string, string> | null;
+declare const $_POST: Record<string, string> | null;
+declare const $_SERVER: JamPhpServer | null;
+declare const $_FILES: JamPhpFiles | null;
+declare const $_ENV: Record<string, string> | null;

package/lib/platform.js

@@ -1,72 +0,0 @@
-"use strict";
-
-function parseNodeLibcFromReport(report) {
-  if (!report || !report.header) return null;
-  if (report.header.glibcVersionRuntime) return "glibc";
-
-  let reportText = JSON.stringify(report).toLowerCase();
-  if (reportText.includes("musl")) return "musl";
-  return null;
-}
-
-function detectLibc(runtime) {
-  if (runtime.platform !== "linux") return null;
-
-  let forced = runtime.env.JAM_LIBC;
-  if (forced === "glibc" || forced === "musl") return forced;
-
-  let fromReport = parseNodeLibcFromReport(runtime.report);
-  if (fromReport) return fromReport;
-
-  return "glibc";
-}
-
-function resolveTarget(platform, arch, libc) {
-  if (platform === "darwin" && arch === "arm64") return "darwin-arm64";
-  if (platform === "darwin" && arch === "x64") return "darwin-x64";
-
-  if (platform === "linux" && arch === "x64" && libc === "glibc") return "linux-x64";
-  if (platform === "linux" && arch === "arm64" && libc === "glibc") return "linux-arm64";
-  if (platform === "linux" && libc === "musl") {
-    throw new Error(
-      `Linux musl is not supported yet: platform=${platform} arch=${arch} libc=${libc}`
-    );
-  }
-
-  throw new Error(
-    `Unsupported platform for Jam npm package: platform=${platform} arch=${arch} libc=${libc || "n/a"}`
-  );
-}
-
-function binaryFileName(platform) {
-  return platform === "win32" ? "jam.exe" : "jam";
-}
-
-function getRuntimeDescriptor(overrides) {
-  let platform = overrides?.platform ?? process.platform;
-  let arch = overrides?.arch ?? process.arch;
-  let report =
-    overrides?.report ??
-    (process.report && typeof process.report.getReport === "function"
-      ? process.report.getReport()
-      : null);
-  let env = overrides?.env ?? process.env;
-
-  let libc = detectLibc({ platform, env, report });
-  let target = resolveTarget(platform, arch, libc);
-
-  return {
-    arch,
-    libc,
-    platform,
-    target,
-    binaryName: binaryFileName(platform),
-  };
-}
-
-module.exports = {
-  binaryFileName,
-  detectLibc,
-  getRuntimeDescriptor,
-  resolveTarget,
-};

package/lib/resolve-binary.js

@@ -1,30 +0,0 @@
-"use strict";
-
-let {
-  packageNameForTarget,
-  resolveOptionalPackageBinaryPath,
-} = require("./resolve-optional-package");
-let { getRuntimeDescriptor } = require("./platform");
-
-function resolveBinaryPath() {
-  let fromEnv = process.env.JAM_BINARY_PATH;
-  if (fromEnv) return fromEnv;
-
-  let descriptor = getRuntimeDescriptor();
-  let optionalPath = resolveOptionalPackageBinaryPath(descriptor);
-  if (optionalPath) return optionalPath;
-
-  let packageName = packageNameForTarget(descriptor.target);
-
-  if (!packageName) {
-    throw new Error(`No optional dependency package is configured for ${descriptor.target}.`);
-  }
-
-  throw new Error(
-    `Jam optional dependency package not installed for ${descriptor.target}: ${packageName}. Try reinstalling with optional dependencies enabled.`
-  );
-}
-
-module.exports = {
-  resolveBinaryPath,
-};

package/lib/resolve-optional-package.js

@@ -1,43 +0,0 @@
-"use strict";
-
-let fs = require("node:fs");
-let path = require("node:path");
-
-let TARGET_TO_PACKAGE = {
-  "darwin-arm64": "jam-darwin-arm64",
-  "darwin-x64": "jam-darwin-x64",
-  "linux-x64": "jam-linux-x64",
-  "linux-arm64": "jam-linux-arm64",
-};
-
-function packageNameForTarget(target) {
-  return TARGET_TO_PACKAGE[target] || null;
-}
-
-function packageRootFromName(packageName) {
-  try {
-    let packageJsonPath = require.resolve(`${packageName}/package.json`, {
-      paths: [path.join(__dirname, "..")],
-    });
-    return path.dirname(packageJsonPath);
-  } catch {
-    return null;
-  }
-}
-
-function resolveOptionalPackageBinaryPath(runtimeDescriptor) {
-  let packageName = packageNameForTarget(runtimeDescriptor.target);
-  if (!packageName) return null;
-
-  let packageRoot = packageRootFromName(packageName);
-  if (!packageRoot) return null;
-
-  let binaryPath = path.join(packageRoot, "bin", runtimeDescriptor.binaryName);
-  if (!fs.existsSync(binaryPath)) return null;
-  return binaryPath;
-}
-
-module.exports = {
-  packageNameForTarget,
-  resolveOptionalPackageBinaryPath,
-};