jam 0.9.3 → 0.10.0

package/README.md

@@ -1,6 +1,6 @@
 # jam
 
-`jam` serves JavaScript and TypeScript files as HTTP routes with isolated per-request execution.
+`jam` is the canonical Jam install package.
 
 ## Usage
 
@@ -8,56 +8,21 @@
 jam [flags] [scripts-dir]
 ```
 
-## Common Commands
+## Notes
 
-```sh
-# Serve scripts from ./scripts on port 3000
-jam ./scripts
-
-# Development mode with detailed error pages
-jam --mode development ./scripts
-
-# Use a config file
-jam --config ./jamconfig.json ./scripts
-
-# Enable PHP-style globals
-jam --php ./scripts
-```
-
-For the complete CLI surface, run:
+- `jam` installs the matching `jam-<os>-<arch>` platform package through npm `optionalDependencies`.
+- The platform package provides the Node SEA executable that actually runs the server.
+- This package publishes the ambient `jam` TypeScript types.
 
-```sh
-jam --help
-```
+## Ambient Types
 
-## Minimal Script
+Ambient `jam` types are generated from `packages/jam-node/types/` when this package is built.
+Fixtures/apps consume the published types with:
 
-```ts
-export default {
-  fetch() {
-    return new Response("Hello from Jam");
+```json
+{
+  "compilerOptions": {
+    "types": ["jam"]
   }
-};
+}
 ```
-
-Saved as `scripts/app.ts`, this route is available at `/app`.
-
-## Docs
-
-- [Introduction](../../docs/001-introduction.md)
-- [Getting Started](../../docs/002-getting-started.md)
-- [Build a Real App](../../docs/003-writing-scripts.md)
-- [Configuration](../../docs/004-configuration.md)
-- [Runtime APIs](../../docs/005-runtime-apis.md)
-- [Templates](../../docs/006-templates.md)
-- [Deployment](../../docs/007-deployment.md)
-
-## Development
-
-`jam` has two entry points with different roles:
-
-- `bin/jam.js`: Node-facing dispatch shim for npm usage.
-- `src/entry.ts`: Bun runtime CLI entrypoint compiled into platform binaries.
-
-For repeatable runtime engineering workflows, see the repo-local skills index:
-[`../../skills/README.md`](../../skills/README.md).

package/bin/jam.js

@@ -1,22 +1,5 @@
 #!/usr/bin/env node
 
-// 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/entry.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.
-
-import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
@@ -25,8 +8,6 @@ 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}`;
@@ -72,61 +53,11 @@ function resolvePlatformBinary(packageName) {
   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() {
   let packageName = resolvePlatformPackageName();
 
@@ -144,36 +75,12 @@ function main() {
     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 (installError === null && maybeRunDevFallback(args)) {
-      return;
-    }
-
-    let message = installError instanceof Error
-      ? installError.message
-      : error instanceof Error
-        ? error.message
-        : String(error);
+    let message = error instanceof Error
+      ? error.message
+      : String(error);
     process.stderr.write(
-      `[jam] Could not find platform binary package ${packageName}. ` +
-      `Try reinstalling dependencies. (${message})\n`
+      `[jam] Could not find the installed platform binary ${packageName}. ` +
+      `Reinstall the \`jam\` package so npm can restore the matching optional dependency. (${message})\n`
     );
     process.exit(1);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jam",
-  "version": "0.9.3",
+  "version": "0.10.0",
   "description": "An application server for isolated JavaScript",
   "license": "MIT",
   "author": "Michael Jackson <mjijackson@gmail.com>",
@@ -29,28 +29,22 @@
     ]
   },
   "optionalDependencies": {
-    "jam-darwin-arm64": "0.9.3",
-    "jam-darwin-x64": "0.9.3",
-    "jam-linux-arm64": "0.9.3",
-    "jam-linux-x64": "0.9.3"
-  },
-  "dependencies": {
-    "@jridgewell/trace-mapping": "^0.3.31",
-    "typescript": "^5.6.3"
+    "jam-darwin-arm64": "0.10.0",
+    "jam-darwin-x64": "0.10.0",
+    "jam-linux-arm64": "0.10.0",
+    "jam-linux-x64": "0.10.0"
   },
   "devDependencies": {
-    "@types/node": "^22.15.31",
-    "bun-types": "^1.2.8"
+    "@types/node": "^24.0.0",
+    "typescript": "^5.6.3"
   },
   "engines": {
-    "bun": ">=1.2"
+    "node": ">=24.14.0"
   },
   "scripts": {
+    "build": "node ./scripts/build-types.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 && bun build ./src/worker-thread.ts --target=bun --outfile ./dist/worker-thread.js"
+    "typecheck": "pnpm run build && tsc -p tsconfig.json",
+    "test": "node --eval \"\""
   }
 }

package/types/jam/index.d.ts

@@ -46,10 +46,135 @@ declare module "jam:test" {
     operator: string;
   }
 
+  export type AssertPredicate =
+    | RegExp
+    | (new (...args: unknown[]) => object)
+    | ((thrown: unknown) => boolean)
+    | object
+    | Error;
+
   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;
+    function ok(value: unknown, message?: string | Error): asserts value;
+    function equal(actual: unknown, expected: unknown, message?: string | Error): void;
+    function notEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function fail(message?: string | Error): never;
+    function fail(
+      actual: unknown,
+      expected: unknown,
+      message?: string | Error,
+      operator?: string,
+      stackStartFn?: Function
+    ): never;
+    function ifError(value: unknown): void;
+    function match(string: string, regexp: RegExp, message?: string | Error): void;
+    function doesNotMatch(string: string, regexp: RegExp, message?: string | Error): void;
+    function strictEqual<T>(actual: unknown, expected: T, message?: string | Error): asserts actual is T;
+    function notStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function deepEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function deepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function notDeepEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function notDeepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function throws(
+      fn: () => unknown,
+      message?: string | Error
+    ): void;
+    function throws(
+      fn: () => unknown,
+      expected: AssertPredicate,
+      message?: string | Error
+    ): void;
+    function doesNotThrow(
+      fn: () => unknown,
+      message?: string | Error
+    ): void;
+    function doesNotThrow(
+      fn: () => unknown,
+      expected: AssertPredicate,
+      message?: string | Error
+    ): void;
+    function rejects(
+      promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+      message?: string | Error
+    ): Promise<void>;
+    function rejects(
+      promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+      expected: AssertPredicate,
+      message?: string | Error
+    ): Promise<void>;
+    function doesNotReject(
+      promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+      message?: string | Error
+    ): Promise<void>;
+    function doesNotReject(
+      promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+      expected: AssertPredicate,
+      message?: string | Error
+    ): Promise<void>;
+    function partialDeepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+  }
+
+  export function strict(value: unknown, message?: string | Error): asserts value;
+
+  export namespace strict {
+    export { AssertionError, strict };
+
+    function ok(value: unknown, message?: string | Error): asserts value;
+    function equal<T>(actual: unknown, expected: T, message?: string | Error): asserts actual is T;
+    function notEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function fail(message?: string | Error): never;
+    function fail(
+      actual: unknown,
+      expected: unknown,
+      message?: string | Error,
+      operator?: string,
+      stackStartFn?: Function
+    ): never;
+    function ifError(value: unknown): void;
+    function match(string: string, regexp: RegExp, message?: string | Error): void;
+    function doesNotMatch(string: string, regexp: RegExp, message?: string | Error): void;
+    function strictEqual<T>(actual: unknown, expected: T, message?: string | Error): asserts actual is T;
+    function notStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function deepEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function deepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function notDeepEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function notDeepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function throws(
+      fn: () => unknown,
+      message?: string | Error
+    ): void;
+    function throws(
+      fn: () => unknown,
+      expected: AssertPredicate,
+      message?: string | Error
+    ): void;
+    function doesNotThrow(
+      fn: () => unknown,
+      message?: string | Error
+    ): void;
+    function doesNotThrow(
+      fn: () => unknown,
+      expected: AssertPredicate,
+      message?: string | Error
+    ): void;
+    function rejects(
+      promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+      message?: string | Error
+    ): Promise<void>;
+    function rejects(
+      promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+      expected: AssertPredicate,
+      message?: string | Error
+    ): Promise<void>;
+    function doesNotReject(
+      promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+      message?: string | Error
+    ): Promise<void>;
+    function doesNotReject(
+      promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+      expected: AssertPredicate,
+      message?: string | Error
+    ): Promise<void>;
+    function partialDeepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
   }
 
   export interface SpyCall {
@@ -73,6 +198,102 @@ declare module "jam:test" {
   export function restoreAll(): void;
 }
 
+declare module "jam:test/strict" {
+  export class AssertionError extends Error {
+    actual: unknown;
+    expected: unknown;
+    operator: string;
+  }
+
+  export type AssertPredicate = import("jam:test").AssertPredicate;
+
+  export function ok(value: unknown, message?: string | Error): asserts value;
+  export function equal<T>(actual: unknown, expected: T, message?: string | Error): asserts actual is T;
+  export function notEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+  export function fail(message?: string | Error): never;
+  export function fail(
+    actual: unknown,
+    expected: unknown,
+    message?: string | Error,
+    operator?: string,
+    stackStartFn?: Function
+  ): never;
+  export function ifError(value: unknown): void;
+  export function match(string: string, regexp: RegExp, message?: string | Error): void;
+  export function doesNotMatch(string: string, regexp: RegExp, message?: string | Error): void;
+  export function strictEqual<T>(actual: unknown, expected: T, message?: string | Error): asserts actual is T;
+  export function notStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+  export function deepEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+  export function deepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+  export function notDeepEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+  export function notDeepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+  export function throws(
+    fn: () => unknown,
+    message?: string | Error
+  ): void;
+  export function throws(
+    fn: () => unknown,
+    expected: AssertPredicate,
+    message?: string | Error
+  ): void;
+  export function doesNotThrow(
+    fn: () => unknown,
+    message?: string | Error
+  ): void;
+  export function doesNotThrow(
+    fn: () => unknown,
+    expected: AssertPredicate,
+    message?: string | Error
+  ): void;
+  export function rejects(
+    promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+    message?: string | Error
+  ): Promise<void>;
+  export function rejects(
+    promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+    expected: AssertPredicate,
+    message?: string | Error
+  ): Promise<void>;
+  export function doesNotReject(
+    promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+    message?: string | Error
+  ): Promise<void>;
+  export function doesNotReject(
+    promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+    expected: AssertPredicate,
+    message?: string | Error
+  ): Promise<void>;
+  export function partialDeepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+  export function strict(value: unknown, message?: string | Error): asserts value;
+
+  export namespace strict {
+    export {
+      AssertionError,
+      deepEqual,
+      deepStrictEqual,
+      doesNotMatch,
+      doesNotReject,
+      doesNotThrow,
+      equal,
+      fail,
+      ifError,
+      match,
+      notDeepEqual,
+      notDeepStrictEqual,
+      notEqual,
+      notStrictEqual,
+      ok,
+      partialDeepStrictEqual,
+      rejects,
+      strict,
+      strictEqual,
+      throws
+    };
+  }
+
+  export default strict;
+}
+
 declare type JamPhpFile = {
   name: string;
   type: string;