@nubjs/nub 0.0.42 → 0.0.45

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nub contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# Nub
+
+TypeScript-first developer supertool for Node.js. Run `.ts`/`.tsx` files directly on your installed Node, a faster `npm run`, a pnpm-compatible package manager, and a built-in Node version manager — no config, no lock-in, no nub-specific public APIs.
+
+**Documentation:** https://nubjs.com/docs
+
+## Install
+
+```sh
+# macOS / Linux
+curl -fsSL https://nubjs.com/install.sh | bash
+
+# Windows (PowerShell)
+irm https://nubjs.com/install.ps1 | iex
+
+# Or via npm
+npm install -g @nubjs/nub
+```
+
+## Quickstart
+
+```sh
+# Run TypeScript directly — no tsconfig, no build step
+nub server.ts
+
+# Run package.json scripts (faster than npm/pnpm run)
+nub run dev
+nub run build
+
+# Execute a local or remote binary
+nubx vitest --run
+
+# Watch mode — restart on change
+nub watch server.ts
+```
+
+## What Nub does
+
+- **TypeScript just works.** Files ending in `.ts`, `.tsx`, `.mts`, `.cts`, `.jsx` execute directly. Enums, decorators, parameter properties, and namespaces are handled. Source maps work in error traces.
+- **The `.env` loading is built in.** Workspace-aware, with `${VAR}` expansion and `.env.local` / `.env.production` layering.
+- **The script runner is faster.** Running `nub run` resolves scripts, adds `node_modules/.bin` to PATH, and runs lifecycle hooks — without the per-invocation Node bootstrap that `npm run` / `pnpm run` pay.
+- **Auto-flag injection.** Experimental Node features are unflagged based on your Node version; opt out with `--no-experimental-*`.
+- **The tsconfig paths resolve.** A path like `@lib/utils` resolves via `compilerOptions.paths` with no build step. Extensionless and data-format imports (`.jsonc`, `.json5`, `.toml`, `.yaml`) work too.
+- **Polyfills.** `Temporal`, `URLPattern`, `RegExp.escape`, `Error.isError`, `Promise.try`, `navigator` — feature-detected, native wins.
+- **Package management.** Commands such as `nub install` / `add` / `remove` are pnpm-compatible on the CLI and lockfile-compatible with whatever the project already uses (npm / pnpm / bun round-trip, yarn read-only) — Nub does not impose its own lockfile format.
+- **Node version management.** Nub provisions and pins the project's Node version, so `nvm` / `corepack` are not needed.
+
+## How it works
+
+Nub is not a Node fork. It is a Rust CLI that orchestrates your installed Node via Node's own extension surfaces — `module.registerHooks()`, `--import` preloads, V8 flag injection, an N-API addon for fast transpilation, and a per-invocation PATH shim. Code targeting Node runs on Nub byte-for-byte. For orchestration without augmentation, use `nub run --node`.
+
+There are no nub-specific public APIs to import, no `nub:*` module namespace, and no config field you author named after the tool. Adopting Nub is reversible — the project keeps running under plain Node and your existing package manager.
+
+## Requirements
+
+Nub runs on your installed Node, version **18.19.0 or newer**. The fast tier (sync `module.registerHooks()`) engages on Node **22.15+**; versions 18.19–22.14 run in a compatibility tier via async `module.register()`. Supported platforms: macOS (arm64, x64), Linux (x64, arm64), Windows (x64).
+
+## License
+
+MIT — see [LICENSE](./LICENSE). Full docs at https://nubjs.com/docs.

package/bin/launch.js

@@ -57,6 +57,64 @@ function resolveBinary(verb) {
 // POSIX single-quote a string for safe embedding in the sh trampoline.
 function shq(s) { return `'${String(s).replace(/'/g, "'\\''")}'`; }
 
+// True iff `p` is executable by THIS process (the +x bits that matter to us).
+function isExecutable(p) {
+  try { fs.accessSync(p, fs.constants.X_OK); return true; } catch { return false; }
+}
+
+// Make `binPath` runnable by us, returning a path that IS executable — `binPath`
+// itself when we can fix it in place, otherwise a user-owned executable copy.
+//
+// npm strips +x on extract from any file that isn't a `bin`-field entry, and the
+// platform packages declare no `bin` field, so the native binary lands 0o644. The
+// install-time `postinstall.js` chmods it back — but when npm SKIPS lifecycle scripts
+// (npm v12's default, or `ignore-scripts=true`) that never runs, leaving a 0o644
+// binary at runtime. The launcher's in-place chmod recovers the common case (we own
+// the file). It CANNOT recover the canonical container case: `root` does `npm i -g`,
+// the image drops to a non-root `USER`, and that user's first `nub` can neither run
+// the 0o644 binary nor chmod a file it doesn't own — `spawn` dies EACCES (verified:
+// scripts-off install + non-root run + root-owned 0o644 binary). For THAT case we
+// copy the binary into a user-owned cache dir at 0o755 and run the copy. This is the
+// scripts-off complement to postinstall's install-time chmod: self-heal that holds
+// even when we're not the binary's owner. Best-effort; returns the original path if
+// every recovery fails (the caller surfaces the spawn error).
+function ensureExecutable(binPath, verb) {
+  if (process.platform === "win32") return binPath; // .exe needs no +x bit
+  if (isExecutable(binPath)) return binPath;
+  // Common case: we own the file (e.g. `sudo`-free user-prefix install) — chmod in place.
+  try { fs.chmodSync(binPath, 0o755); } catch {}
+  if (isExecutable(binPath)) return binPath;
+  // Non-owner / read-only store: stage a user-owned executable copy in the cache.
+  // Key the copy on the source path + size + mtime so a binary upgrade re-stages and
+  // we never exec stale bytes; an existing fresh+executable copy is reused as-is.
+  try {
+    const st = fs.statSync(binPath);
+    const base = process.env.XDG_CACHE_HOME ||
+      (os.homedir() && os.homedir() !== "/" ? path.join(os.homedir(), ".cache") : null);
+    if (!base) return binPath;
+    // The copy's FILENAME must stay the bare verb (`nub`/`nubx`): the native binary
+    // selects its verb from argv[0]'s basename, and the healed sh trampoline `exec`s
+    // this path with no argv0 override — a tagged filename like `nubx-<tag>` would make
+    // `nubx` misclassify as plain `nub`. So the staleness tag goes in the DIRECTORY,
+    // and the executable keeps its real name: `<cache>/nub/bin/<tag>/<verb>`.
+    const tag = `${st.size}-${Math.trunc(st.mtimeMs)}`;
+    const dir = path.join(base, "nub", "bin", tag);
+    fs.mkdirSync(dir, { recursive: true });
+    const dest = path.join(dir, verb);
+    if (isExecutable(dest)) {
+      const dst = fs.statSync(dest);
+      if (dst.size === st.size) return dest; // already staged, current, runnable
+    }
+    // Atomic stage: copy to a unique temp in the same dir, chmod, rename into place.
+    const tmp = path.join(dir, `.${verb}.${process.pid}.${Date.now()}.tmp`);
+    fs.copyFileSync(binPath, tmp);
+    fs.chmodSync(tmp, 0o755);
+    fs.renameSync(tmp, dest);
+    if (isExecutable(dest)) return dest;
+  } catch {}
+  return binPath; // give up; caller's spawn surfaces the real error
+}
+
 // Verify a PATH entry demonstrably resolves to OUR launcher before replacing it —
 // never clobber an unrelated `nub` (there is an unrelated nub@1.0.0 on npm). For a
 // symlink, realpath(entry) must equal our launcher's realpath. For a pnpm cmd-shim
@@ -128,15 +186,18 @@ function healPathEntry(verb, nativePath) {
 // argv0Name: the verb this stub represents ("nubx" for bin/nubx; undefined => nub).
 module.exports = function launch(argv0Name) {
   const verb = argv0Name || "nub";
-  const binPath = resolveBinary(verb);
+  const resolved = resolveBinary(verb);
   // Ensure the platform binary is executable. npm strips the +x bit on install from
   // files that aren't `bin`-field entries, and the platform package declares no bin
-  // field — so the staged-executable binary lands 0o644 and both spawnSync (below)
-  // and the healed sh trampoline's `exec` would EACCES / "Permission denied". The old
-  // postinstall did this chmod; doing it in the launcher covers EVERY package manager
-  // (npm strips, others may not) and runs before the heal writes a trampoline that
-  // exec's this binary. Best-effort; harmless if already executable.
-  try { fs.chmodSync(binPath, 0o755); } catch {}
+  // field — so the binary lands 0o644 and both spawn (below) and the healed sh
+  // trampoline's `exec` would EACCES / "Permission denied". `postinstall.js` chmods it
+  // at INSTALL time, but that's skipped under npm v12's scripts-off default (or
+  // `ignore-scripts=true`); ensureExecutable is the runtime net for that. It chmods in
+  // place when we own the file, and falls back to a user-owned executable COPY when we
+  // don't (the root-installs-then-drops-to-non-root container case the launcher's bare
+  // chmod cannot reach). Returns a path that IS executable; the heal + spawn both use
+  // it so the fast-path trampoline targets the runnable file too.
+  const binPath = ensureExecutable(resolved, verb);
   // Self-heal the PATH entry on first POSIX call so later calls skip Node entirely.
   healPathEntry(verb, binPath);
   // This call still runs through Node; spawn the native binary. argv0 basename of

package/package.json

@@ -1,10 +1,26 @@
 {
   "name": "@nubjs/nub",
-  "version": "0.0.42",
+  "version": "0.0.45",
   "description": "TypeScript-first developer supertool — a fast script runner and TS runtime powered by Node.js",
   "license": "MIT",
   "repository": "https://github.com/nubjs/nub",
-  "homepage": "https://github.com/nubjs/nub",
+  "homepage": "https://nubjs.com",
+  "bugs": {
+    "url": "https://github.com/nubjs/nub/issues"
+  },
+  "keywords": [
+    "typescript",
+    "nodejs",
+    "runtime",
+    "ts-node",
+    "tsx",
+    "script-runner",
+    "package-manager",
+    "node-version-manager"
+  ],
+  "engines": {
+    "node": ">=18.19.0"
+  },
   "bin": {
     "nub": "bin/nub",
     "nubx": "bin/nubx"
@@ -15,16 +31,18 @@
   "files": [
     "bin",
     "platform.js",
-    "postinstall.js"
+    "postinstall.js",
+    "README.md",
+    "LICENSE"
   ],
   "optionalDependencies": {
-    "@nubjs/nub-darwin-arm64": "0.0.42",
-    "@nubjs/nub-darwin-x64": "0.0.42",
-    "@nubjs/nub-linux-x64": "0.0.42",
-    "@nubjs/nub-linux-x64-musl": "0.0.42",
-    "@nubjs/nub-linux-arm64": "0.0.42",
-    "@nubjs/nub-linux-arm64-musl": "0.0.42",
-    "@nubjs/nub-win32-x64": "0.0.42",
-    "@nubjs/nub-win32-arm64": "0.0.42"
+    "@nubjs/nub-darwin-arm64": "0.0.45",
+    "@nubjs/nub-darwin-x64": "0.0.45",
+    "@nubjs/nub-linux-x64": "0.0.45",
+    "@nubjs/nub-linux-x64-musl": "0.0.45",
+    "@nubjs/nub-linux-arm64": "0.0.45",
+    "@nubjs/nub-linux-arm64-musl": "0.0.45",
+    "@nubjs/nub-win32-x64": "0.0.45",
+    "@nubjs/nub-win32-arm64": "0.0.45"
   }
 }