@nimbus-sh/core 0.1.0

package/dist/runtime/router-basename.d.ts

@@ -0,0 +1,36 @@
+/**
+ * router-basename.ts — Auto-inject React Router `basename` for the /preview/
+ * base path so `<NavLink to="/docs">` lands at `/preview/docs` with no
+ * additional config in the user's source.
+ *
+ * Applied at VFS serve time inside vite-dev-server.ts `serveTransformed()`,
+ * BEFORE esbuild's TS/JSX transform (source is easier to regex on).
+ *
+ * Patterns handled:
+ *   A. createBrowserRouter(routes)                    → inject { basename }
+ *   B. createBrowserRouter(routes, { ... })           → merge if no basename
+ *   C. <BrowserRouter ...>                            → add basename attr
+ *   D. <BrowserRouter basename="x">                   → leave alone
+ *
+ * Never overrides user-set values. Opt-out:
+ *   - Explicit basename in source (per pattern)
+ *   - Comment `// nimbus-no-basename` anywhere in the file
+ *   - `nimbusInjectBasename: false` in vite.config.ts (plumbed by caller)
+ *
+ * Scope guard: only transforms likely router entry files (main.tsx, index.tsx,
+ * App.tsx, root.tsx, router.tsx). node_modules is excluded by the caller.
+ */
+/**
+ * Should this VFS path be considered for router-basename injection?
+ * Fast filter before we pay for regex scans on the file body.
+ */
+export declare function shouldProcessForRouter(vfsPath: string): boolean;
+/**
+ * Inject a `basename` into React Router `createBrowserRouter` / <BrowserRouter>
+ * calls in the source, unless the user has set one or opted out.
+ *
+ * Returns the transformed source. Always safe — if no pattern matches,
+ * returns the input unchanged.
+ */
+export declare function injectRouterBasename(src: string, basePath: string): string;
+//# sourceMappingURL=router-basename.d.ts.map

package/dist/runtime/router-basename.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-basename.d.ts","sourceRoot":"","sources":["../../src/runtime/router-basename.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA6BH;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAO/D;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAwE1E"}

package/dist/runtime/router-basename.js

@@ -0,0 +1,310 @@
+/**
+ * router-basename.ts — Auto-inject React Router `basename` for the /preview/
+ * base path so `<NavLink to="/docs">` lands at `/preview/docs` with no
+ * additional config in the user's source.
+ *
+ * Applied at VFS serve time inside vite-dev-server.ts `serveTransformed()`,
+ * BEFORE esbuild's TS/JSX transform (source is easier to regex on).
+ *
+ * Patterns handled:
+ *   A. createBrowserRouter(routes)                    → inject { basename }
+ *   B. createBrowserRouter(routes, { ... })           → merge if no basename
+ *   C. <BrowserRouter ...>                            → add basename attr
+ *   D. <BrowserRouter basename="x">                   → leave alone
+ *
+ * Never overrides user-set values. Opt-out:
+ *   - Explicit basename in source (per pattern)
+ *   - Comment `// nimbus-no-basename` anywhere in the file
+ *   - `nimbusInjectBasename: false` in vite.config.ts (plumbed by caller)
+ *
+ * Scope guard: only transforms likely router entry files (main.tsx, index.tsx,
+ * App.tsx, root.tsx, router.tsx). node_modules is excluded by the caller.
+ */
+/**
+ * Opt-out comment pattern. Matches a line-leading `//` comment containing the
+ * directive. Intentionally strict so that mere mentions of the directive in
+ * quoted strings, JSX text, or long-form comments do not accidentally disable
+ * injection (e.g., docstrings that reference the opt-out won't opt out).
+ *
+ * Examples that trigger opt-out:
+ *   // nimbus-no-basename
+ *   //   nimbus-no-basename
+ *   // nimbus-no-basename — disables auto-inject here
+ *
+ * Examples that DO NOT trigger (by design):
+ *   const s = "// nimbus-no-basename";          // string literal
+ *   // add the comment "// nimbus-no-basename"  // quoted inside comment
+ */
+const OPT_OUT_RE = /^[ \t]*\/\/[ \t]*nimbus-no-basename\b/m;
+/** Files that are likely router entries. Path is the VFS path. */
+const ENTRY_PATTERNS = [
+    /(?:^|\/)main\.(tsx|ts|jsx|js|mjs)$/i,
+    /(?:^|\/)index\.(tsx|ts|jsx|js|mjs)$/i,
+    /(?:^|\/)App\.(tsx|ts|jsx|js|mjs)$/i,
+    /(?:^|\/)root\.(tsx|ts|jsx|js|mjs)$/i,
+    /(?:^|\/)router(?:\.config)?\.(tsx|ts|jsx|js|mjs)$/i,
+    /(?:^|\/)routes\.(tsx|ts|jsx|js|mjs)$/i,
+];
+/**
+ * Should this VFS path be considered for router-basename injection?
+ * Fast filter before we pay for regex scans on the file body.
+ */
+export function shouldProcessForRouter(vfsPath) {
+    if (!vfsPath)
+        return false;
+    // Never touch vendored code — our seed/user code lives under src/, not node_modules.
+    if (vfsPath.includes('/node_modules/'))
+        return false;
+    if (vfsPath.startsWith('node_modules/'))
+        return false;
+    const normalized = '/' + vfsPath.replace(/^\/+/, '');
+    return ENTRY_PATTERNS.some((re) => re.test(normalized));
+}
+/**
+ * Inject a `basename` into React Router `createBrowserRouter` / <BrowserRouter>
+ * calls in the source, unless the user has set one or opted out.
+ *
+ * Returns the transformed source. Always safe — if no pattern matches,
+ * returns the input unchanged.
+ */
+export function injectRouterBasename(src, basePath) {
+    // Fast short-circuits
+    if (!src || src.length === 0)
+        return src;
+    if (OPT_OUT_RE.test(src))
+        return src;
+    // Only scan further if the source MENTIONS the relevant router APIs.
+    // Using substring checks (not regex) to keep the fast path cheap.
+    const mentionsFactory = src.indexOf('createBrowserRouter') !== -1;
+    const mentionsComponent = src.indexOf('BrowserRouter') !== -1;
+    if (!mentionsFactory && !mentionsComponent)
+        return src;
+    const basenameLiteral = JSON.stringify(basePath);
+    let out = src;
+    // ── Pattern B first: createBrowserRouter(routes, { ...options })
+    // Handled first so Pattern A (single-arg) doesn't accidentally gobble the
+    // second-arg object. Non-greedy body match to stop at the first balanced-
+    // looking `}` — good enough for typical hand-written code.
+    //
+    // Matches:
+    //   createBrowserRouter(routes, {})
+    //   createBrowserRouter(routes, { future: { ... } })
+    //   createBrowserRouter([...], {\n  basename: '/x',\n})
+    //
+    // Multi-line safe because we use [\s\S].
+    out = out.replace(/\bcreateBrowserRouter\s*\(\s*([\s\S]*?)\s*,\s*\{([\s\S]*?)\}\s*\)/g, (match, routes, opts) => {
+        // Balance check: if `routes` contains unmatched parens, our regex ate too much.
+        if (!isBalanced(routes))
+            return match;
+        if (/\bbasename\s*:/.test(opts))
+            return match; // user set basename
+        // Trim opts to make formatting tidy; add leading space for readability.
+        const trimmedOpts = opts.replace(/^[\s,]*/, '').replace(/[\s,]*$/, '');
+        const body = trimmedOpts
+            ? `basename: ${basenameLiteral}, ${trimmedOpts}`
+            : `basename: ${basenameLiteral}`;
+        return `createBrowserRouter(${routes}, { ${body} })`;
+    });
+    // ── Pattern A: createBrowserRouter(routes)   — single-arg form
+    // Must NOT match calls that already have a second arg (handled by B above).
+    // Detect "single arg" by looking at the char right after the first balanced-
+    // looking close — if it's `)`, no second arg.
+    //
+    // We implement this manually rather than with a clever regex: scan for
+    // `createBrowserRouter(`, find the matching close paren, and check whether
+    // a comma (at depth 0) exists between them.
+    out = scanAndReplaceCreateBrowserRouterSingleArg(out, basenameLiteral);
+    // ── Pattern C: <BrowserRouter ...>  and  <BrowserRouter />
+    // Adds `basename="/preview"` if not already present. Opening tag only.
+    //
+    // Matches (examples):
+    //   <BrowserRouter>             attrs="", end=">"
+    //   <BrowserRouter />           attrs="", end=" />"
+    //   <BrowserRouter window={w}>  attrs=" window={w}", end=">"
+    //   <BrowserRouter\n  x={y}\n>  attrs="\n  x={y}\n", end=">"
+    //
+    // The regex keeps `attrs` non-empty only when real attribute chars
+    // exist; bare whitespace before `/>` ends up in `end` so we preserve
+    // the user's original whitespace style.
+    out = out.replace(/<BrowserRouter((?:\s+[^>\/\s][^>]*?)?)(\s*\/?\s*>)/g, (match, attrs, end) => {
+        if (attrs && /\bbasename\s*=/.test(attrs))
+            return match;
+        // Inject basename AFTER the attribute block (before `end`'s leading
+        // whitespace). `attrs` is either empty or starts with whitespace.
+        return `<BrowserRouter${attrs} basename=${basenameLiteral}${end}`;
+    });
+    return out;
+}
+// ── Helpers ─────────────────────────────────────────────────────────────
+/** Check that parens + brackets + braces in `s` are balanced. */
+function isBalanced(s) {
+    let p = 0, b = 0, c = 0;
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        if (ch === '(')
+            p++;
+        else if (ch === ')')
+            p--;
+        else if (ch === '[')
+            b++;
+        else if (ch === ']')
+            b--;
+        else if (ch === '{')
+            c++;
+        else if (ch === '}')
+            c--;
+        if (p < 0 || b < 0 || c < 0)
+            return false;
+    }
+    return p === 0 && b === 0 && c === 0;
+}
+/**
+ * Find every `createBrowserRouter(ARGS)` where ARGS at depth-0 contains no
+ * comma (i.e. exactly one argument), and replace with
+ * `createBrowserRouter(ARGS, { basename: "..." })`.
+ *
+ * Skips any call whose argument list has a second (or more) comma-separated
+ * top-level item, since Pattern B handled those.
+ */
+function scanAndReplaceCreateBrowserRouterSingleArg(src, basenameLiteral) {
+    const needle = 'createBrowserRouter';
+    let out = '';
+    let i = 0;
+    while (i < src.length) {
+        const hit = src.indexOf(needle, i);
+        if (hit < 0) {
+            out += src.slice(i);
+            break;
+        }
+        // Ensure this is a standalone identifier (not "myCreateBrowserRouter" or
+        // "createBrowserRouterFoo"). Check the chars immediately before and after.
+        const before = hit > 0 ? src[hit - 1] : '';
+        const after = src[hit + needle.length];
+        const isIdentChar = (c) => /[\w$]/.test(c);
+        if (isIdentChar(before) || isIdentChar(after)) {
+            out += src.slice(i, hit + needle.length);
+            i = hit + needle.length;
+            continue;
+        }
+        // Skip optional whitespace, then require `(`.
+        let j = hit + needle.length;
+        while (j < src.length && /\s/.test(src[j]))
+            j++;
+        if (src[j] !== '(') {
+            out += src.slice(i, j);
+            i = j;
+            continue;
+        }
+        // Find matching `)` at depth 0 of this `(`, tracking nested parens,
+        // brackets, braces, and string/template-literal bodies. Also note if a
+        // depth-0 `,` exists (→ multi-arg form, skip; Pattern B handled it).
+        const parenStart = j;
+        let depthP = 1, depthB = 0, depthC = 0;
+        let hasTopLevelComma = false;
+        let k = parenStart + 1;
+        let strQuote = null;
+        let inLineComment = false;
+        let inBlockComment = false;
+        let inTemplate = false;
+        // Note: we skip template-literal interpolation depth tracking for simplicity.
+        // If a user embeds `createBrowserRouter(...)` inside a template literal, we
+        // just leave it alone (rare pattern).
+        while (k < src.length) {
+            const ch = src[k];
+            const nx = src[k + 1];
+            if (inLineComment) {
+                if (ch === '\n')
+                    inLineComment = false;
+                k++;
+                continue;
+            }
+            if (inBlockComment) {
+                if (ch === '*' && nx === '/') {
+                    inBlockComment = false;
+                    k += 2;
+                    continue;
+                }
+                k++;
+                continue;
+            }
+            if (strQuote) {
+                if (ch === '\\') {
+                    k += 2;
+                    continue;
+                }
+                if (ch === strQuote)
+                    strQuote = null;
+                k++;
+                continue;
+            }
+            if (inTemplate) {
+                if (ch === '\\') {
+                    k += 2;
+                    continue;
+                }
+                if (ch === '`')
+                    inTemplate = false;
+                k++;
+                continue;
+            }
+            if (ch === '/' && nx === '/') {
+                inLineComment = true;
+                k += 2;
+                continue;
+            }
+            if (ch === '/' && nx === '*') {
+                inBlockComment = true;
+                k += 2;
+                continue;
+            }
+            if (ch === '"' || ch === "'") {
+                strQuote = ch;
+                k++;
+                continue;
+            }
+            if (ch === '`') {
+                inTemplate = true;
+                k++;
+                continue;
+            }
+            if (ch === '(')
+                depthP++;
+            else if (ch === ')') {
+                depthP--;
+                if (depthP === 0 && depthB === 0 && depthC === 0)
+                    break;
+            }
+            else if (ch === '[')
+                depthB++;
+            else if (ch === ']')
+                depthB--;
+            else if (ch === '{')
+                depthC++;
+            else if (ch === '}')
+                depthC--;
+            else if (ch === ',' && depthP === 1 && depthB === 0 && depthC === 0) {
+                hasTopLevelComma = true;
+            }
+            k++;
+        }
+        if (depthP !== 0) {
+            // Unbalanced — can't reason about this call. Emit as-is.
+            out += src.slice(i, k);
+            i = k;
+            continue;
+        }
+        const parenEnd = k; // index of the matching `)`
+        if (hasTopLevelComma) {
+            // Multi-arg — Pattern B already processed it (or refused to). Skip.
+            out += src.slice(i, parenEnd + 1);
+            i = parenEnd + 1;
+            continue;
+        }
+        // Single-arg form — inject `, { basename: "..." }` before the `)`.
+        out += src.slice(i, parenEnd);
+        out += `, { basename: ${basenameLiteral} }`;
+        out += ')';
+        i = parenEnd + 1;
+    }
+    return out;
+}

package/dist/runtime/ruby-green-threads.d.ts

@@ -0,0 +1,136 @@
+/**
+ * ruby-green-threads.ts - the concurrency substrate for ruby.wasm.
+ *
+ * This is a kernel component, not a shim to make one library pass. It is the
+ * model every guest runtime on Nimbus can use, so the contract is written down
+ * rather than left to be inferred.
+ *
+ * ── Why fibers ─────────────────────────────────────────────────────────────
+ *
+ * ruby.wasm has one thread of execution; `Thread.new` raises
+ * NotImplementedError. Running the block inline and returning a thread-shaped
+ * object is not a thread - it is a function call wearing a thread's name, and
+ * every program that uses threads for concurrency deadlocks or answers wrongly
+ * with no error.
+ *
+ * A fiber is a real suspension, and - this is the load-bearing property -
+ * one that survives a workerd request boundary. See "State ownership" below.
+ * So a thread is a fiber, and the scheduler here runs them: M:1 green threads,
+ * the model Ruby itself used before 1.9 and the model Node still uses to serve
+ * thousands of concurrent connections on one thread.
+ *
+ * ── 1. Scheduling policy ───────────────────────────────────────────────────
+ *
+ * Round-robin, run-to-park, no priorities. Each scheduling pass walks the
+ * threads in creation order and resumes every one whose wait condition is
+ * satisfied. A resumed thread runs until it parks or finishes.
+ *
+ * There is NO preemption, and none is possible: nothing can interrupt a fiber
+ * that does not yield. A CPU-bound thread therefore holds the process until it
+ * finishes. That is bounded and observable rather than silent - the virtual
+ * socket kernel's response timer fires and the caller gets a 504 naming the
+ * port, instead of a request that hangs forever. It is not hidden and it is
+ * not a bug to be "fixed" by going back to inline execution.
+ *
+ * ── 2. The park set ────────────────────────────────────────────────────────
+ *
+ * Every operation that can block MUST park, or it is a latent deadlock. The
+ * complete set, and where each lives:
+ *
+ *   Thread#join, Thread#value                    here
+ *   Queue#pop (empty), SizedQueue#push (full)    here
+ *   Mutex#lock (held), ConditionVariable#wait    here
+ *   sleep, on a thread or the main body          here
+ *   Timeout.timeout's deadline                   here
+ *   TCPServer#accept                             ruby-socket-shim
+ *   IO.select, over Nimbus sockets or a timeout  ruby-socket-shim
+ *   IO.pipe read on an empty pipe                ruby-socket-shim
+ *
+ * ── 2a. Why a timed wait cannot wait here ──────────────────────────────────
+ *
+ * workerd freezes the clock inside a turn - a deliberate timing-attack
+ * mitigation, measured at 0ms elapsed across 200,000 Time.now reads. So a wait
+ * that watches the clock can never end: it consumes the process's whole CPU
+ * budget and the invocation is killed with nothing to show for it. Ruby's own
+ * sleep is exactly that loop, which is why nothing here calls it.
+ *
+ * The clock belongs to the host, so a deadline is something to hand back
+ * rather than something to watch. A parked thread records when it wants
+ * waking; the main body hands the earliest such moment to the host and yields;
+ * the host waits on a real timer and resumes the process with the clock moved
+ * on. Every wait shape above therefore takes a deadline, and one that has no
+ * deadline and nothing that could ever satisfy it is reported as a deadlock.
+ *
+ * That clock also has a RESOLUTION - Date.now, whole milliseconds - and a
+ * deadline landing between two of them is one it can never report reaching.
+ * `Time.now + 0.2` is exactly that deadline, because the double nearest 0.2 is
+ * 0.2000000000000000111: measured on workerd, the host resumes the process at
+ * precisely +200ms and the guest finds itself 1.1e-17s short, re-arms for the
+ * remainder, is resumed again with the clock unmoved, and burns the budget one
+ * round trip at a time. So a deadline is rounded UP onto the clock's grid as
+ * it enters the scheduler, which is the only form of it that can be reached.
+ *
+ * Ruby exports the synchronisation primitives under two names each - ::Queue
+ * and Thread::Queue - and defines both itself. BOTH have to resolve to the
+ * implementations here: the real ones wait for an OS thread to wake them,
+ * which a fiber can never be, so the first green thread that reaches one stops
+ * the process for good. WEBrick's timeout watcher reaches Thread::Queue#pop on
+ * its second connection, which is exactly how that was found.
+ *
+ * Deliberately NOT parked, and why it is safe: reads and writes on a CONNECTED
+ * socket descriptor suspend the wasm stack through JSPI instead of yielding to
+ * peers. An accepted connection's request is already buffered when it is
+ * accepted, and a dialed connection's response is produced by the host within
+ * the same request, so neither can wait on another green thread - they cannot
+ * deadlock. They do not interleave either: a thread blocked in a socket read
+ * stops its peers until the bytes arrive.
+ *
+ * ── 3. State ownership across the request boundary ─────────────────────────
+ *
+ * A workerd request context will NOT resume a wasm stack that a different
+ * request suspended. Measured: three requests inside one context all serve in
+ * 6ms; the first request in a new context times out at 30s. So what a thread
+ * is suspended in decides whether it survives:
+ *
+ *   Fiber stacks, Ruby objects, thread-locals   Ruby VM linear memory - SURVIVES
+ *   A JSPI-suspended wasm stack                 bound to its request - DOES NOT
+ *   Accept queues, connection byte queues       host JS (the kernel) - SURVIVES
+ *
+ * The rule that falls out: a thread that must outlive the current request may
+ * only ever be suspended by Fiber.yield. That is why every entry in the park
+ * set above routes through Threading.park, and why the socket shim's blocking
+ * accept parks instead of awaiting the host.
+ *
+ * ── 4. Termination ─────────────────────────────────────────────────────────
+ *
+ * Thread#kill and process shutdown raise inside the fiber (Fiber#raise), so
+ * `ensure` blocks run and sockets close. Nothing is left parked holding a
+ * descriptor: when the main body finishes, every surviving thread is killed
+ * the same way, which is Ruby's own semantics for process exit.
+ *
+ * ── 5. Honest limits ───────────────────────────────────────────────────────
+ *
+ * No parallelism: one thread of execution, so CPU-bound work in a fiber blocks
+ * everyone until it yields. No preemption: scheduling points are the park set,
+ * nothing else. For I/O-bound work - per-connection handlers, watchdogs,
+ * timeouts - that is the whole of what threads are for here. CPU-parallel work
+ * sharing a heap is not available at this level, and it is not available at any
+ * other level either: every resident process is a DO Facet and facet siblings
+ * serialise on CPU, so there is nowhere to offload it to.
+ *
+ * The sharp edge of no preemption is a hand-rolled busy-wait: `until Time.now
+ * - t0 > 0.05; end` has no scheduling point, so nothing can reach it, and
+ * because the clock is frozen (§2a) it does not merely spin - it never ends.
+ * That is the one wait shape the scheduler cannot rescue. A program that wants
+ * to wait has to say so, through one of the park-set entries above.
+ *
+ * ── 6. The same model, one layer down ──────────────────────────────────────
+ *
+ * runtime/wasi-threads.ts is this contract at the HOST layer: green threads as
+ * multiple wasm instances over one shared linear memory, for guests whose
+ * threads are pthreads rather than fibers. Same park set, same run-to-park
+ * policy, same deadlock verdict, same honest limits. Two implementations of one
+ * concurrency model at two layers - not two models.
+ */
+export declare const RUBY_GREEN_THREADS: string;
+//# sourceMappingURL=ruby-green-threads.d.ts.map

package/dist/runtime/ruby-green-threads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ruby-green-threads.d.ts","sourceRoot":"","sources":["../../src/runtime/ruby-green-threads.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqIG;AACH,eAAO,MAAM,kBAAkB,QAiwB9B,CAAC"}