bug: npx t3 fails silently on Linux (no Linux prebuilt for node-pty)

[ryaneggz]

Summary

npx t3 exits with code 1 and zero bytes of output (both stdout and stderr empty) on Linux x64. The CLI itself is reachable — installing with --ignore-scripts and invoking the bin directly works correctly. The silent failure is in the install hook for node-pty@1.1.0, whose published prebuilds/ directory contains only darwin-{arm64,x64} and win32-{arm64,x64} — no Linux prebuilds. On Linux the install falls through to node-gyp rebuild, which fails when make / build-essential is absent. npx propagates the non-zero exit but suppresses install-script stderr, so the user sees nothing.

Reproduction

Environment: Node v22.22.2, Linux x64 (WSL2, glibc), no build-essential installed.

$ npx --yes -p t3@0.0.22 t3 --help 2>npx-stderr.log 1>npx-stdout.log
$ echo "exit=$? stdout=$(wc -c <npx-stdout.log) stderr=$(wc -c <npx-stderr.log)"
exit=1 stdout=0 stderr=0

Smoking gun (from ~/.npm/_logs/*-debug-0.log)

info run node-pty@1.1.0 install node_modules/node-pty node scripts/prebuild.js || node-gyp rebuild
info run node-pty@1.1.0 install { code: 1, signal: null }
gyp ERR! stack Error: not found: make
verbose exit 1

The install-script stderr is captured in the npm debug log but never surfaced to the user when invoked via npx. From the user's perspective, npx t3 exits 1 with no explanation.

Proof the CLI itself is fine

$ mkdir t3-direct && cd t3-direct && npm init -y >/dev/null
$ npm install --ignore-scripts t3@0.0.22
added 199 packages
$ node node_modules/t3/dist/bin.mjs --help
DESCRIPTION
  Run the T3 Code server.

USAGE
  t3 <subcommand> [flags] [<cwd>]
... (full help output, exit 0)

apps/server/src/bin.ts (and the bundled dist/bin.mjs) only lazy-imports node-pty from inside PTY-using code paths, so --help, --version, auth, etc. don't actually need a working PTY backend at module-load time. The CLI is reachable on Linux today — the install hook is what's blocking it.

Proof from the published tarball

$ npm pack t3@0.0.22 && tar -xzf t3-0.0.22.tgz
$ npm install --ignore-scripts t3@0.0.22
$ ls node_modules/node-pty/prebuilds/
darwin-arm64  darwin-x64  win32-arm64  win32-x64
# no linux-* directory

Affected users

Linux users without build-essential / make — the default state for most fresh containers, devcontainers, GitHub Actions runners on ubuntu-latest images that don't pre-install build tools, and casual users running npx t3 to try the tool. macOS and Windows are unaffected because prebuilds exist there.

Suggested fix

Move node-pty from dependencies → optionalDependencies in apps/server/package.json:

   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.111",
     "@effect/platform-bun": "catalog:",
     "@effect/platform-node": "catalog:",
     "@effect/sql-sqlite-bun": "catalog:",
     "@opencode-ai/sdk": "^1.3.15",
     "@pierre/diffs": "catalog:",
     "effect": "catalog:",
-    "node-pty": "^1.1.0",
     "open": "^10.1.0"
+  },
+  "optionalDependencies": {
+    "node-pty": "^1.1.0"
   },

A failed node-pty install becomes non-fatal; --help / auth / other PTY-free subcommands keep working; only PTY-requiring subcommands fail (with a real error message instead of silently exiting 1). When node-pty does install successfully (macOS/Windows always; Linux with build tools), behaviour is unchanged. One-line diff, no breaking change.

Alternatives considered

1. Ship Linux prebuilds for node-pty. Larger blast radius — likely upstream CI matrix work in node-pty itself, or vendoring/forking. Worth doing eventually, but doesn't need to block this fix.
2. Try/catch + diagnostic at bin entrypoint. Wrap the node-pty import and print a clear "PTY backend unavailable; install build tools or use a release with prebuilt binaries" message. Doesn't fix the install — just makes the failure loud. Useful as a complement to fix oxc stack #1, not a replacement.

References

• apps/server/package.json — line listing "node-pty": "^1.1.0" in dependencies
• apps/server/src/bin.ts — entrypoint (dist/bin.mjs after tsdown bundle, with #!/usr/bin/env node shebang)
• node_modules/node-pty/prebuilds/ in the installed package — Linux directory absent

Happy to send a PR with the one-line fix if maintainers agree this is the desired direction.