refactor: migrate from ts-node to native Node ESM

.claude/skills/indexing-diagnostics/SKILL.md

@@ -1288,7 +1288,7 @@ Path A is faster, doesn't require server config changes, and works against stagi
 
 ### Path A — direct token mint (the common case)
 
-The user runs `mise run claude-prerender-token <realm-url> [<seed>]`. The script (`packages/realm-server/scripts/claude-prerender-token.ts`, executed via `ts-node --transpileOnly` from inside `packages/realm-server`) mints a `boxel-session` JWT the same way the indexer does — same claims, same HS256/1d, same `JSON.stringify({ <realmUrl>: <jwt> })` map shape that lands in `localStorage['boxel-session']`. Faithful CLI port of `buildCreatePrerenderAuth` (`packages/realm-server/prerender/auth.ts`).
+The user runs `mise run claude-prerender-token <realm-url> [<seed>]`. The script (`packages/realm-server/scripts/claude-prerender-token.ts`, executed via `node` from inside `packages/realm-server`) mints a `boxel-session` JWT the same way the indexer does — same claims, same HS256/1d, same `JSON.stringify({ <realmUrl>: <jwt> })` map shape that lands in `localStorage['boxel-session']`. Faithful CLI port of `buildCreatePrerenderAuth` (`packages/realm-server/prerender/auth.ts`).
 
 **The CLI is intentionally minimal: just `<realm-url>` and an optional `<seed>` positional.** If `<seed>` is omitted the script reads from `process.stdin` — interactively that's a masked TTY paste prompt (each char echoes as `*`, paste-friendly, no shell history); piped/redirected stdin is read in full and trimmed. Optional flags: `--user <matrix-id>` (required only for system realms), `--permissions <list>`, `--output <path>`, `--no-output`. That's it. The token is realm-scoped, not card-scoped — Claude builds the `/render` URL itself for whichever card it's investigating.
 

.eslintrc.js

@@ -53,8 +53,8 @@ module.exports = {
       'error',
       { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
     ],
-    // Keep new code "erasable" so it can run under Node's
-    // `--experimental-strip-types` without ts-node.
+    // Keep new code "erasable" so Node can run it via
+    // `--experimental-strip-types` (type-only syntax that vanishes when stripped).
     '@typescript-eslint/parameter-properties': [
       'error',
       { prefer: 'class-property' },

.github/workflows/boxel-cli-publish.yml

@@ -125,7 +125,7 @@ jobs:
           PR_BODY: ${{ steps.pr.outputs.body }}
         run: |
           set -euo pipefail
-          RESULT=$(NODE_NO_WARNINGS=1 pnpm exec ts-node --transpileOnly scripts/compute-release.ts)
+          RESULT=$(NODE_NO_WARNINGS=1 pnpm exec node scripts/compute-release.ts)
           echo "Compute result: $RESULT"
           {
             echo "json<<__REL_EOF__"
@@ -205,7 +205,7 @@ jobs:
           RELEASE_BODY_FILE="$BODY_FILE" \
           CHANGELOG_FRAGMENT_FILE="$FRAGMENT_FILE" \
           NODE_NO_WARNINGS=1 pnpm --filter @cardstack/boxel-cli exec \
-            ts-node --transpileOnly scripts/generate-release-notes.ts
+            node scripts/generate-release-notes.ts
           echo "has=true" >> "$GITHUB_OUTPUT"
           echo "body_file=$BODY_FILE" >> "$GITHUB_OUTPUT"
 
@@ -441,7 +441,7 @@ jobs:
           RELEASE_BODY_FILE="$BODY_FILE" \
           CHANGELOG_FRAGMENT_FILE="$FRAGMENT_FILE" \
           NODE_NO_WARNINGS=1 pnpm --filter @cardstack/boxel-cli exec \
-            ts-node --transpileOnly scripts/generate-release-notes.ts
+            node scripts/generate-release-notes.ts
           FRAG_FILE="$FRAGMENT_FILE" node -e '
             const fs = require("fs");
             const path = "packages/boxel-cli/CHANGELOG.md";

.github/workflows/ci-software-factory.yaml

@@ -75,7 +75,10 @@ jobs:
           shopt -s dotglob
           cp -a .test-web-assets-artifact/. ./
       - name: Install Playwright Browsers
-        run: pnpm exec playwright install
+        # --with-deps also apt-installs the system libraries Playwright needs;
+        # without it CI fails with "Host system is missing dependencies to run
+        # browsers".
+        run: pnpm exec playwright install --with-deps
         working-directory: packages/software-factory
       - name: Run Node tests
         if: ${{ matrix.shard.index == 1 }}

.github/workflows/ci.yaml

@@ -595,7 +595,7 @@ jobs:
           cp -a .test-web-assets-artifact/. ./
       - name: Compute shard test modules
         id: shard_modules
-        run: echo "modules=$(node scripts/shard-test-modules.js ${{ matrix.shardIndex }} ${{ matrix.shardTotal }})" >> "$GITHUB_OUTPUT"
+        run: echo "modules=$(node scripts/shard-test-modules.cjs ${{ matrix.shardIndex }} ${{ matrix.shardTotal }})" >> "$GITHUB_OUTPUT"
         working-directory: packages/realm-server
       # Warm the test images from the GHCR mirror so the services
       # below start from a local image instead of an unauthenticated Docker Hub

eslint/erasable-syntax-selectors.cjs

@@ -3,7 +3,7 @@
 // Selectors for TypeScript syntax that Node cannot run via
 // `--experimental-strip-types`, which only handles "erasable" TS —
 // syntax that vanishes once type annotations are stripped. New code
-// must avoid these so it can run under Node natively, without ts-node.
+// must avoid these so it can run under Node natively.
 //
 // Shared by the root `.eslintrc.js`, `packages/ai-bot/.eslintrc.js`
 // (which is `root: true`), and `packages/catalog/.eslintrc.cjs` (which

mise-tasks/claude-prerender-token

@@ -2,4 +2,4 @@
 #MISE description="Mint a realm-scoped boxel-session JWT (the indexer's auth shape) and write to /tmp/claude-prerender.json for Claude to drive a live browser render"
 #MISE dir="packages/realm-server"
 
-exec ts-node --transpileOnly ./scripts/claude-prerender-token.ts "$@"
+exec node ./scripts/claude-prerender-token.ts "$@"

mise-tasks/infra/clear-modules-cache

@@ -6,4 +6,4 @@
 echo "Clearing modules cache..."
 PGPORT="${PGPORT:-5435}" PGDATABASE="${PGDATABASE:-boxel}" \
   NODE_NO_WARNINGS=1 \
-  ts-node --transpileOnly scripts/clear-modules-cache.ts
+  node scripts/clear-modules-cache.ts

mise-tasks/infra/start-admin

@@ -2,4 +2,4 @@
 #MISE description="Start the Matrix admin console (port 8080)"
 #MISE dir="packages/matrix"
 
-exec ts-node --transpileOnly ./scripts/admin-console
+exec node ./scripts/admin-console.ts

mise-tasks/infra/stop-synapse

@@ -2,4 +2,4 @@
 #MISE description="Stop the Matrix Synapse server"
 #MISE dir="packages/matrix"
 
-exec ts-node --transpileOnly ./scripts/synapse.ts stop
+exec node ./scripts/synapse.ts stop

mise-tasks/lib/dev-common.sh

@@ -230,7 +230,7 @@ _kill_tree_walk() {
 
 # Sweep orphaned dev-stack processes scoped to this checkout. mise's task
 # supervisor reparents long-running task scripts to init, and the wrapper
-# layers above ts-node (pnpm, npm exec, run-p, vite, start-server-and-test)
+# layers above the node entrypoints (pnpm, npm exec, run-p, vite, start-server-and-test)
 # routinely exit without relaying SIGTERM to their grandchildren — so a
 # tree-walk from a known pid can't reach all of them via PPID. SIGTERM first
 # for anything that listens, brief grace, then SIGKILL.
@@ -245,11 +245,15 @@ _kill_tree_walk() {
 #
 # The patterns:
 #   - mise-tasks/services/* — the bash service entrypoints
-#   - node_modules.*--transpileOnly (worker|main|prerender) — ts-node
-#     grandchildren that actually hold the realm/worker/prerender ports
-#     (4201/4202, 4210/4211, 4221/4222). Wrappers that just invoke ts-node
-#     don't `exec` it, so killing the wrapper alone leaves the ts-node
-#     grandchild reparented to init with its port still bound.
+#   - node <entry>.ts (main / worker-manager / prerender/*-server) — the
+#     native-Node grandchildren that actually hold the realm/worker/prerender
+#     ports (4201/4202, 4210/4211, 4221/4222). They run with
+#     cwd=packages/realm-server and relative argv, so $REPO_ROOT can't anchor
+#     the match; the entry names plus a distinctive flag keep it
+#     Boxel-specific, and the early-return guard above prevents
+#     sibling-checkout collisions. Wrappers that just invoke node don't
+#     `exec` it, so killing the wrapper alone leaves the node grandchild
+#     reparented to init with its port still bound.
 #   - scripts/vite-serve.js — the host start wrapper that spawns the
 #     actual vite child. Can't anchor to $REPO_ROOT because pnpm invokes
 #     it as `node scripts/vite-serve.js` (relative argv, cwd-relative),
@@ -287,7 +291,7 @@ sweep_orphaned_services() {
     return 0
   fi
   REPO_ROOT_RE="$(printf '%s' "$REPO_ROOT" | sed -E 's/[][\\.*^$+?(){}|]/\\&/g')"
-  TSNODE_RE="${REPO_ROOT_RE}/packages/realm-server/node_modules.*--transpileOnly (worker|main|prerender)"
+  REALM_NODE_RE="(main\.ts .*--realmsRootPath|worker-manager\.ts .*--allPriorityCount|prerender/(prerender|manager)-server\.ts)"
   VITE_SERVE_RE="scripts/vite-serve\.js"
   VITE_BIN_RE="${REPO_ROOT_RE}/packages/host/.*vite/bin/vite\.js"
   SAT_RE="${REPO_ROOT_RE}/.*node_modules/.*start-server-and-test/src/bin/start\.js"
@@ -296,7 +300,7 @@ sweep_orphaned_services() {
 
   for sig in TERM KILL; do
     pkill -"$sig" -f "${REPO_ROOT_RE}/mise-tasks/services/" 2>/dev/null || true
-    pkill -"$sig" -f "$TSNODE_RE" 2>/dev/null || true
+    pkill -"$sig" -f "$REALM_NODE_RE" 2>/dev/null || true
     pkill -"$sig" -f "$VITE_SERVE_RE" 2>/dev/null || true
     pkill -"$sig" -f "$VITE_BIN_RE" 2>/dev/null || true
     pkill -"$sig" -f "$SAT_RE" 2>/dev/null || true

mise-tasks/services/ai-bot

@@ -6,4 +6,4 @@ MATRIX_URL="${MATRIX_URL_VAL}" \
   NODE_NO_WARNINGS=1 \
   PGPORT="${PGPORT}" \
   PGDATABASE="${PGDATABASE}" \
-  exec ts-node --transpileOnly main
+  exec node main.ts

mise-tasks/services/bot-runner

@@ -6,4 +6,4 @@ MATRIX_URL="${MATRIX_URL_VAL}" \
   NODE_NO_WARNINGS=1 \
   PGPORT="${PGPORT}" \
   PGDATABASE="${PGDATABASE}" \
-  exec ts-node --transpileOnly main
+  exec node main.ts

mise-tasks/services/prerender

@@ -44,7 +44,7 @@ fi
 # host is actually browser-ready.
 if [ -z "$ENV_MODE" ]; then
   HOST_URL="${BOXEL_HOST_URL:-$DEFAULT_HOST_URL}" \
-    ts-node --transpileOnly ./scripts/wait-for-host-standby.ts || exit $?
+    node ./scripts/wait-for-host-standby.ts || exit $?
 fi
 
 # In local HTTPS dev (vite on https://localhost:4200 with HTTP/2),
@@ -61,8 +61,8 @@ NODE_ENV=development \
   NODE_NO_WARNINGS=1 \
   BOXEL_HOST_URL="${BOXEL_HOST_URL:-$DEFAULT_HOST_URL}" \
   PRERENDER_STANDBY_TIMEOUT_MS="${PRERENDER_STANDBY_TIMEOUT_MS:-}" \
-  ts-node \
-  --transpileOnly prerender/prerender-server \
+  node \
+  prerender/prerender-server.ts \
   --port="${PRERENDER_PORT}" \
   --count="${PRERENDER_COUNT:-1}" \
   2>&1 | "$LOG_TEE" prerender

mise-tasks/services/prerender-mgr

@@ -23,8 +23,8 @@ NODE_ENV=development \
   NODE_NO_WARNINGS=1 \
   PRERENDER_MANAGER_VERBOSE_LOGS=false \
   PRERENDER_MULTIPLEX="${PRERENDER_MULTIPLEX:-1}" \
-  ts-node \
-  --transpileOnly prerender/manager-server \
+  node \
+  prerender/manager-server.ts \
   --port=${PRERENDER_MANAGER_PORT:-$PRERENDER_MGR_PORT} \
   --exit-on-signal \
   2>&1 | "$LOG_TEE" prerender-manager

mise-tasks/services/realm-server

@@ -23,9 +23,9 @@ cleanup_icons_server() {
   fi
 }
 # EXIT runs cleanup unconditionally. INT/TERM additionally exit 0 so that the
-# 143-on-Ctrl-C from the ts-node pipeline below isn't reported by mise /
+# 143-on-Ctrl-C from the node pipeline below isn't reported by mise /
 # run-p as "task failed" — see mise-tasks/services/worker for the broader
-# rationale. Real crashes still propagate (ts-node faulting on its own
+# rationale. Real crashes still propagate (node faulting on its own
 # leaves the trap unfired, so pipefail's 143-aware exit code wins).
 # The signal handler clears the EXIT trap before exiting so cleanup doesn't
 # run twice in succession.
@@ -44,7 +44,7 @@ if [ "${SKIP_CATALOG:-}" != "true" ]; then
 fi
 
 if [ -z "$MATRIX_REGISTRATION_SHARED_SECRET" ]; then
-  MATRIX_REGISTRATION_SHARED_SECRET=$(ts-node --transpileOnly "$SCRIPTS_DIR/matrix-registration-secret.ts")
+  MATRIX_REGISTRATION_SHARED_SECRET=$(node "$SCRIPTS_DIR/matrix-registration-secret.ts")
   export MATRIX_REGISTRATION_SHARED_SECRET
 fi
 
@@ -93,8 +93,7 @@ LOW_CREDIT_THRESHOLD="${LOW_CREDIT_THRESHOLD:-2000}" \
   MATRIX_URL="${MATRIX_URL_VAL}" \
   REALM_SERVER_MATRIX_USERNAME=realm_server \
   ENABLE_FILE_WATCHER=true \
-  ts-node \
-  --transpileOnly main \
+  node main.ts \
   --port="${REALM_PORT}" \
   --matrixURL="${MATRIX_URL_VAL}" \
   --realmsRootPath="${REALMS_ROOT}" \

mise-tasks/services/realm-server-base

@@ -9,7 +9,7 @@
 trap 'exit 0' INT TERM
 
 if [ -z "$MATRIX_REGISTRATION_SHARED_SECRET" ]; then
-  MATRIX_REGISTRATION_SHARED_SECRET=$(ts-node --transpileOnly ./scripts/matrix-registration-secret.ts)
+  MATRIX_REGISTRATION_SHARED_SECRET=$(node ./scripts/matrix-registration-secret.ts)
   export MATRIX_REGISTRATION_SHARED_SECRET
 fi
 
@@ -22,8 +22,7 @@ NODE_ENV=development \
   GRAFANA_SECRET="shhh! it's a secret" \
   MATRIX_URL="${MATRIX_URL_VAL}" \
   REALM_SERVER_MATRIX_USERNAME=realm_server \
-  ts-node \
-  --transpileOnly main \
+  node main.ts \
   --port=4201 \
   --matrixURL="${MATRIX_URL_VAL}" \
   --realmsRootPath='./realms/localhost_4201_base' \

mise-tasks/services/test-realms

@@ -55,7 +55,7 @@ fi
 pnpm --dir=../skills-realm skills:setup
 
 if [ -z "$MATRIX_REGISTRATION_SHARED_SECRET" ]; then
-  MATRIX_REGISTRATION_SHARED_SECRET=$(ts-node --transpileOnly "$SCRIPTS_DIR/matrix-registration-secret.ts")
+  MATRIX_REGISTRATION_SHARED_SECRET=$(node "$SCRIPTS_DIR/matrix-registration-secret.ts")
   export MATRIX_REGISTRATION_SHARED_SECRET
 fi
 
@@ -68,8 +68,7 @@ NODE_ENV=test \
   GRAFANA_SECRET="shhh! it's a secret" \
   MATRIX_URL="${MATRIX_URL_VAL}" \
   REALM_SERVER_MATRIX_USERNAME=realm_server \
-  ts-node \
-  --transpileOnly main \
+  node main.ts \
   --port="${TEST_PORT}" \
   --matrixURL="${MATRIX_URL_VAL}" \
   --realmsRootPath="${REALMS_TEST_ROOT}" \

mise-tasks/services/worker

@@ -13,7 +13,7 @@ set -o pipefail
 # SIGTERM this script during Ctrl-C; without this trap the pipefail-aware
 # pipe below exits 143, mise reports it as "task failed", and run-p prints
 # `ERROR: "start:worker-development" exited with 143` — pure shutdown
-# noise. Real crashes (ts-node faulting on its own) still propagate, since
+# noise. Real crashes (node faulting on its own) still propagate, since
 # the trap only fires when *we* receive the signal.
 trap 'exit 0' INT TERM
 
@@ -40,8 +40,7 @@ NODE_ENV=development \
   REALM_SERVER_MATRIX_USERNAME=realm_server \
   LOW_CREDIT_THRESHOLD=2000 \
   OPENROUTER_REALM_URL="${REALM_BASE_URL}/openrouter/" \
-  ts-node \
-  --transpileOnly worker-manager \
+  node worker-manager.ts \
   --allPriorityCount="${WORKER_ALL_PRIORITY_COUNT:-1}" \
   --highPriorityCount="${WORKER_HIGH_PRIORITY_COUNT:-0}" \
   --port="${WORKER_PORT}" \

mise-tasks/services/worker-base

@@ -16,8 +16,7 @@ NODE_ENV=development \
   REALM_SECRET_SEED="shhh! it's a secret" \
   REALM_SERVER_MATRIX_USERNAME=realm_server \
   LOW_CREDIT_THRESHOLD=2000 \
-  ts-node \
-  --transpileOnly worker-manager \
+  node worker-manager.ts \
   --port=4213 \
   --matrixURL="${MATRIX_URL_VAL}" \
   --prerendererUrl="${PRERENDER_MGR_URL}" \

mise-tasks/services/worker-test

@@ -28,8 +28,7 @@ NODE_ENV=test \
   REALM_SECRET_SEED="shhh! it's a secret" \
   REALM_SERVER_MATRIX_USERNAME=realm_server \
   LOW_CREDIT_THRESHOLD=2000 \
-  ts-node \
-  --transpileOnly worker-manager \
+  node worker-manager.ts \
   --port="${WORKER_TEST_PORT}" \
   --matrixURL="${MATRIX_URL_VAL}" \
   --prerendererUrl="${PRERENDER_MGR_URL}" \

packages/ai-bot/README.md

@@ -37,8 +37,8 @@ Start the server with `pnpm start` or `pnpm start-dev` for live reload.
 
 ### Async graphs (Clinic Bubbleprof)
 
-- Run Bubbleprof attached to ts-node:
-  - `AI_BOT_PROF=1 DISABLE_MATRIX_JS_LOGGING=1 LOG_LEVELS="ai-bot=debug" pnpm dlx clinic bubbleprof --dest .clinic/ai-bot-bp -- node --require ts-node/register/transpile-only main.ts`
+- Run Bubbleprof attached to the node process:
+  - `AI_BOT_PROF=1 DISABLE_MATRIX_JS_LOGGING=1 LOG_LEVELS="ai-bot=debug" pnpm dlx clinic bubbleprof --dest .clinic/ai-bot-bp -- node main.ts`
   - Drive one interaction; stop with Ctrl+C twice (~200–500ms apart) or send `SIGTERM` from another terminal.
   - Open the report:
     - `pnpm dlx clinic open .clinic/ai-bot-bp`

packages/ai-bot/lib/code-patch-correctness.ts

@@ -1,5 +1,5 @@
 import type { MatrixClient } from 'matrix-js-sdk';
-import type { RoomMessageEventContent } from 'matrix-js-sdk/lib/@types/events';
+import type { RoomMessageEventContent } from 'matrix-js-sdk/lib/@types/events.js';
 
 import { uuidv4 } from '@cardstack/runtime-common';
 import type { PendingCodePatchCorrectnessCheck } from '@cardstack/runtime-common/ai/types';

packages/ai-bot/lib/debug.ts

@@ -1,7 +1,7 @@
 import { setTitle } from './set-title.ts';
 import type OpenAI from 'openai';
 
-import * as Sentry from '@sentry/node';
+import { errorReporter } from './sentry.ts';
 import type { MatrixEvent as DiscreteMatrixEvent } from 'https://cardstack.com/base/matrix-event';
 import {
   getPromptParts,
@@ -78,7 +78,7 @@ To patch a card:\n
         customMessage,
       );
     } catch (error) {
-      Sentry.captureException(error, {
+      errorReporter.captureException(error, {
         extra: {
           roomId: roomId,
           userId: userId,
@@ -133,7 +133,7 @@ To patch a card:\n
         );
       }
     } catch (error) {
-      Sentry.captureException(error, {
+      errorReporter.captureException(error, {
         extra: {
           roomId: roomId,
           userId: userId,

packages/ai-bot/lib/responder.ts

@@ -2,10 +2,10 @@ import { logger } from '@cardstack/runtime-common';
 import { APP_BOXEL_CODE_PATCH_CORRECTNESS_MSGTYPE } from '@cardstack/runtime-common/matrix-constants';
 import { isCommandOrCodePatchResult } from '@cardstack/runtime-common/ai';
 
-import * as Sentry from '@sentry/node';
+import { errorReporter } from './sentry.ts';
 import type { OpenAIError } from 'openai/error';
-import throttle from 'lodash/throttle';
-import type { ISendEventResponse } from 'matrix-js-sdk/lib/matrix';
+import { throttle } from 'lodash-es';
+import type { ISendEventResponse } from 'matrix-js-sdk/lib/matrix.js';
 import type { ChatCompletionMessageFunctionToolCall } from 'openai/resources/chat/completions';
 import type { FunctionToolCall } from '@cardstack/runtime-common/helpers/ai';
 import type OpenAI from 'openai';
@@ -188,7 +188,7 @@ export class Responder {
     if (this.responseState.isStreamingFinished) {
       return;
     }
-    Sentry.captureException(error, {
+    errorReporter.captureException(error, {
       extra: {
         roomId: this.matrixResponsePublisher.roomId,
         agentId: this.matrixResponsePublisher.agentId,

packages/ai-bot/lib/sentry.ts

@@ -0,0 +1,13 @@
+import * as Sentry from '@sentry/node';
+
+// Indirection over Sentry so tests can replace `captureException`. Under native
+// ESM, `import * as Sentry` is a sealed module namespace whose bindings are
+// read-only, so tests can't stub `Sentry.captureException` directly. Calling
+// through this mutable object lets a test swap the method and restore it.
+export const errorReporter = {
+  captureException(
+    ...args: Parameters<typeof Sentry.captureException>
+  ): ReturnType<typeof Sentry.captureException> {
+    return Sentry.captureException(...args);
+  },
+};