@mandujs/core 0.21.0 → 0.22.1

package/src/bundler/fast-refresh-plugin.ts

@@ -0,0 +1,307 @@
+/**
+ * Phase 7.1 B-4 — Fast Refresh boundary injection plugin.
+ *
+ * This Bun.build plugin runs in the `onLoad` phase for every file whose
+ * path matches `.client.tsx?` / `.island.tsx?`. It reads the source,
+ * appends a boundary-registration epilogue that calls
+ * `window.__MANDU_HMR__.acceptFile(<module url>)`, and hands the
+ * augmented source back to Bun for transformation. No AST traversal is
+ * required: the appended code is syntactically isolated (semicolon-
+ * terminated inside a guard) and always parses regardless of the source
+ * it's being concatenated to.
+ *
+ * Why `onLoad` and not a define/transform hook?
+ * ─────────────────────────────────────────────
+ * Bun's plugin API (`onResolve`, `onLoad`, `onStart`) does not expose a
+ * post-transform AST pass. The `onLoad` hook is the only point where we
+ * can affect the source before `reactFastRefresh` runs; it receives the
+ * raw file bytes and returns `{ contents, loader }`. Vite does this via
+ * a Rollup `transform` hook for the same reason.
+ *
+ * The emitted epilogue is intentionally defensive:
+ *
+ *   if (typeof window !== "undefined" && window.__MANDU_HMR__) {
+ *     window.__MANDU_HMR__.acceptFile(<url>);
+ *   }
+ *
+ * This survives three edge cases:
+ *   1. Module evaluated during SSR (no window)   → guard short-circuits.
+ *   2. Preamble not yet loaded                    → `__MANDU_HMR__` absent,
+ *                                                    no throw.
+ *   3. Same module re-evaluated after hot swap    → `acceptFile` is
+ *                                                    idempotent by design.
+ *
+ * Skipping mechanics:
+ *   - In production (`disabled: true`) the plugin short-circuits so we
+ *     don't ship refresh code to users.
+ *   - Files whose path includes `node_modules` are never eligible.
+ *   - A file that already contains a literal `window.__MANDU_HMR__` call
+ *     is trusted — we don't append a second one (idempotent even across
+ *     multiple `Bun.build` passes that bundle a pre-bundled module).
+ *   - URLs exceeding `MAX_ACCEPT_FILE_URL_LEN` (2 KB) or containing
+ *     characters that could escape the inline script context (`</`,
+ *     newline, nul) are rejected with a warning — no boundary emitted.
+ *     See `docs/security/phase-7-1-audit.md` §3 L-01.
+ *
+ * References:
+ *   docs/bun/phase-7-1-diagnostics/fast-refresh-strategy.md §4 (4 phase breakdown)
+ *   docs/bun/phase-7-1-team-plan.md §4 Agent B
+ *   docs/bun/phase-7-2-team-plan.md §3 Agent C H3 (URL length cap)
+ *   docs/security/phase-7-1-audit.md §3 L-01
+ *   https://bun.com/docs/runtime/plugins
+ *   packages/core/src/runtime/fast-refresh-types.ts
+ */
+
+import fs from "fs/promises";
+import type { BunPlugin } from "bun";
+
+import type {
+  BoundaryDecision,
+  FastRefreshPluginOptions,
+} from "../runtime/fast-refresh-types";
+
+// ============================================
+// Exported constants (shared with tests)
+// ============================================
+
+/**
+ * Default include filter. Matches `foo.client.tsx`, `foo.client.ts`,
+ * `foo.island.tsx`, `foo.island.ts`. Deliberately strict — we do NOT
+ * default to every `.tsx` to stay aligned with Mandu's component model
+ * (only explicit client / island files are HMR boundaries; pages and
+ * layouts full-reload to re-run their SSR slot).
+ */
+export const DEFAULT_INCLUDE = /\.(client|island)\.tsx?$/;
+
+/**
+ * Guard regex that detects whether a file already contains an
+ * `acceptFile` call, so multi-pass bundling (e.g. pre-bundled demo
+ * packages) doesn't stack registrations.
+ */
+const ALREADY_INJECTED = /__MANDU_HMR__\s*(?:\?\.)?\s*\.acceptFile\s*\(/;
+
+/**
+ * Phase 7.2 H3 (L-01 audit): cap the length of a URL we will accept into
+ * an `acceptFile()` call. 2 KB is ~8× larger than any realistic Mandu
+ * tmpdir fixture and matches `MAX_BOUNDARY_URL_LEN` suggested by the
+ * audit. Beyond this we refuse to append the boundary — the file simply
+ * falls back to full-reload HMR, which is the safe degradation path.
+ */
+export const MAX_ACCEPT_FILE_URL_LEN = 2048;
+
+/**
+ * Phase 7.2 H3 (L-01 audit): characters or substrings that, if present
+ * inside the URL string, could break out of the emitted inline `<script>`
+ * context. `</` is the classic HTML-in-JS escape; `\n` / `\r` / `\u2028`
+ * / `\u2029` are JS literal terminators; `\x00`-`\x1f` are control chars
+ * the parser will complain about anyway. We reject outright rather than
+ * try to re-escape — these paths are filesystem-authored so the
+ * legitimate case never produces them.
+ */
+const UNSAFE_URL_SEQUENCES = ["</", "\u2028", "\u2029", "<script", "<!--"] as const;
+const UNSAFE_URL_CHARS = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f\r\n]/;
+
+/**
+ * Comment-neutral detector for `node_modules`. Using a forward-slashed
+ * string match is sufficient because Mandu normalizes paths to posix
+ * internally (see `bundler/dev.ts` `normalizeFsPath`).
+ */
+function isInNodeModules(filePath: string): boolean {
+  return (
+    filePath.includes("/node_modules/") || filePath.includes("\\node_modules\\")
+  );
+}
+
+/**
+ * Runtime predicate that decides whether `moduleUrl` is safe to bake
+ * into the inline `<script>` that the plugin emits. Exported so tests
+ * and diagnostic callers can share the exact rule.
+ *
+ * The checks are ordered cheapest-first (length before char-regex before
+ * substring scan) so a successful path short-circuits early. Returns
+ * `{ ok: true }` for accepted URLs and `{ ok: false, reason }` for
+ * rejections — the reason string feeds into the warning printed at
+ * injection time so developers see exactly why their file went
+ * full-reload.
+ */
+export function validateAcceptFileUrl(
+  moduleUrl: string,
+): { ok: true } | { ok: false; reason: string } {
+  if (typeof moduleUrl !== "string") {
+    return { ok: false, reason: "moduleUrl is not a string" };
+  }
+  if (moduleUrl.length === 0) {
+    return { ok: false, reason: "moduleUrl is empty" };
+  }
+  if (moduleUrl.length > MAX_ACCEPT_FILE_URL_LEN) {
+    return {
+      ok: false,
+      reason: `moduleUrl length ${moduleUrl.length} exceeds cap ${MAX_ACCEPT_FILE_URL_LEN}`,
+    };
+  }
+  if (UNSAFE_URL_CHARS.test(moduleUrl)) {
+    return { ok: false, reason: "moduleUrl contains control / newline chars" };
+  }
+  for (const seq of UNSAFE_URL_SEQUENCES) {
+    if (moduleUrl.includes(seq)) {
+      return {
+        ok: false,
+        reason: `moduleUrl contains unsafe substring "${seq}"`,
+      };
+    }
+  }
+  return { ok: true };
+}
+
+// ============================================
+// Pure transform — exported for direct unit tests
+// ============================================
+
+/**
+ * Append the boundary epilogue to `source` unless a prior pass already
+ * did so. Pure function; no file I/O, no side effects. Takes a
+ * `moduleUrl` string the plugin has already resolved (usually a
+ * normalized form of the on-disk path).
+ *
+ * Phase 7.2 H3: hardened with `validateAcceptFileUrl`. When the URL
+ * fails validation we emit the source unchanged and log a single
+ * `console.warn`. The warning path is intentionally non-fatal — a
+ * pathological URL that somehow leaks through is a DX concern
+ * (full-reload HMR still works) not a correctness one.
+ *
+ * The returned string is always safe to pass to Bun's `tsx` loader —
+ * the epilogue is wrapped in a `typeof window` guard, so a single pass
+ * of semicolon insertion at the end of the user's source never produces
+ * an unclosed JSX expression or a dangling string.
+ */
+export function appendBoundary(source: string, moduleUrl: string): string {
+  if (ALREADY_INJECTED.test(source)) return source;
+
+  // Phase 7.2 H3: URL length + escape cap. Rejected URLs fall through
+  // to full-reload HMR without a boundary, preserving correctness.
+  const check = validateAcceptFileUrl(moduleUrl);
+  if (!check.ok) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[Mandu Fast Refresh] acceptFile URL rejected (${check.reason}); ` +
+        `falling back to full-reload for this module.`,
+    );
+    return source;
+  }
+
+  // JSON.stringify here does double duty: (1) it escapes any
+  // backslashes / quotes in the URL path (important on Windows), and
+  // (2) it produces a valid JS string literal even for pathological
+  // inputs (unicode, newline, etc.). We explicitly do NOT accept
+  // moduleUrls from user input — the plugin controls what gets passed.
+  const urlLiteral = JSON.stringify(moduleUrl);
+
+  // The newline before our block is required: if `source` ends with a
+  // `//` line comment, concatenation without `\n` would comment out
+  // our guard. Trailing newline after ensures well-formed EOF.
+  return (
+    source +
+    `\n;if (typeof window !== "undefined" && window.__MANDU_HMR__) {` +
+    ` window.__MANDU_HMR__.acceptFile(${urlLiteral}); }\n`
+  );
+}
+
+/**
+ * Classify a file against the plugin's include filter without touching
+ * the filesystem. Surfaced so tests and dev-mode diagnostics can answer
+ * "would this file have been transformed?" without invoking Bun.build.
+ */
+export function classifyBoundary(
+  filePath: string,
+  options: FastRefreshPluginOptions = {},
+): BoundaryDecision {
+  if (options.disabled === true) {
+    return { accepted: false, reason: "disabled" };
+  }
+  if (isInNodeModules(filePath)) {
+    return { accepted: false, reason: "non-react" };
+  }
+  const include = options.include ?? DEFAULT_INCLUDE;
+  if (!include.test(filePath)) {
+    return { accepted: false, reason: "excluded-by-include" };
+  }
+  return {
+    accepted: true,
+    reason: "matched-include",
+    source: filePath,
+  };
+}
+
+// ============================================
+// Bun plugin factory
+// ============================================
+
+/**
+ * Build a `BunPlugin` that implements Fast Refresh boundary injection.
+ * Consumed by `bundler/build.ts`'s `buildIsland` / `buildPerIslandBundle`
+ * calls — those pass it in through `plugins: [...]` alongside whatever
+ * else the build configures.
+ *
+ * When `options.disabled` is true, a no-op plugin is returned; this is
+ * the production path, where we never want refresh injection on the
+ * wire.
+ */
+export function fastRefreshPlugin(
+  options: FastRefreshPluginOptions = {},
+): BunPlugin {
+  const include = options.include ?? DEFAULT_INCLUDE;
+  const disabled = options.disabled === true;
+
+  return {
+    name: "mandu:fast-refresh-boundary",
+    setup(build) {
+      if (disabled) {
+        // Register a no-op onLoad so the plugin still appears in Bun's
+        // internal diagnostics, but it never matches anything.
+        return;
+      }
+
+      build.onLoad({ filter: include }, async (args) => {
+        // Skip anything under node_modules even if the filter would
+        // have caught it. Pre-bundled packages aren't our concern.
+        if (isInNodeModules(args.path)) {
+          return undefined;
+        }
+
+        let source: string;
+        try {
+          source = await fs.readFile(args.path, "utf-8");
+        } catch (err) {
+          // Bubble up — Bun will surface the read failure as a build
+          // error, which is the correct behavior (a file we matched
+          // but can't read is a genuine fault).
+          throw err;
+        }
+
+        // Normalize to forward slashes so the registered URL is
+        // consistent regardless of platform. `dispatchReplacement`
+        // uses the same normalization shape — this is load-bearing.
+        const normalizedUrl = args.path.replace(/\\/g, "/");
+
+        return {
+          contents: appendBoundary(source, normalizedUrl),
+          loader: (args.path.endsWith(".tsx") ? "tsx" : "ts") as
+            | "tsx"
+            | "ts",
+        };
+      });
+    },
+  };
+}
+
+// ============================================
+// Test helpers
+// ============================================
+
+/**
+ * Expose the `ALREADY_INJECTED` regex so tests can assert that
+ * idempotency is governed by a single source of truth rather than
+ * re-deriving the pattern.
+ * @internal
+ */
+export const _testOnly_ALREADY_INJECTED = ALREADY_INJECTED;

package/src/bundler/hmr-types.ts

@@ -0,0 +1,252 @@
+/**
+ * Phase 7.0 — Shared HMR types (Vite-compat wire format + `ManduHot` runtime API)
+ *
+ * This file is the CONTRACT between Agents A (reliability + #188), B
+ * (incremental bundled import), and C (Vite-compat `import.meta.hot` +
+ * HMR replay + layout-update). Do NOT add logic here — pure types only.
+ *
+ * Source of truth for:
+ *   - `ViteHMRPayload`       — wire format identical to Vite's HMR WebSocket
+ *                              payload, so external devtools / IDE extensions
+ *                              that speak Vite work against Mandu out of the box.
+ *   - `HMREventName`         — Vite built-in event names the client may `on`.
+ *   - `ManduHot`             — runtime-side `import.meta.hot` surface (subset).
+ *   - `HMRReplayEnvelope`    — server-side queue entry for replay after reconnect.
+ *   - `CoalescedChange`      — batched file change handed to the rebuild path.
+ *
+ * References:
+ *   docs/bun/phase-7-team-plan.md §3.1
+ *   docs/bun/phase-7-diagnostics/industry-benchmark.md §2 (Vite API spec)
+ *   packages/core/src/bundler/dev.ts:453 (pre-existing `HMRMessage` — kept)
+ */
+
+// ============================================
+// Vite-compat wire format
+// ============================================
+
+/**
+ * Payload shapes identical to Vite 6 HMR WebSocket wire format.
+ *
+ * Mandu broadcasts these ALONGSIDE the internal `HMRMessage` shape
+ * (dev.ts:453) so a single WS connection serves both:
+ *   - Mandu's own client (consumes the richer internal shape)
+ *   - External devtools / IDE plugins (consume only Vite-compat events)
+ *
+ * The payload structure mirrors Vite's to guarantee compatibility. Do NOT
+ * reshape for "consistency" with the internal format — the value is that
+ * the wire bytes are byte-equivalent to what Vite emits.
+ */
+export type ViteHMRPayload =
+  | { type: "connected" }
+  | {
+      type: "update";
+      updates: Array<{
+        type: "js-update" | "css-update";
+        path: string;
+        acceptedPath: string;
+        timestamp: number;
+      }>;
+    }
+  | { type: "full-reload"; path?: string }
+  | { type: "prune"; paths: string[] }
+  | {
+      type: "error";
+      err: {
+        message: string;
+        stack?: string;
+        id?: string;
+        frame?: string;
+        plugin?: string;
+        loc?: { file: string; line: number; column: number };
+      };
+    }
+  | { type: "custom"; event: string; data?: unknown };
+
+/**
+ * Phase 7.2 — HDR (Hot Data Revalidation) payload.
+ *
+ * Emitted when a `.slot.ts` file changes. Unlike `full-reload`, the
+ * client receives this and re-invokes the route's loader to refetch
+ * props while the React tree stays mounted — form input, scroll,
+ * focused element all survive. Modeled after Remix's HDR.
+ *
+ * The client-side handler (runtime/hmr-client.ts `dispatchReplacement`
+ * in Phase 7.2) wraps the props update in `React.startTransition` so
+ * the browser doesn't flash an intermediate state.
+ */
+export interface HDRPayload {
+  /** Discriminator — NOT a Vite-compat payload (Mandu internal only). */
+  type: "slot-refetch";
+  /** Route id whose loader must re-invoke. Matches manifest `route.id`. */
+  routeId: string;
+  /** Absolute path of the slot file that changed — for logging + dedup. */
+  slotPath: string;
+  /** Monotonic per-server-boot id — compatible with the replay buffer. */
+  rebuildId: number;
+  /** Unix ms — coalescing window for back-to-back edits. */
+  timestamp: number;
+}
+
+/**
+ * Vite built-in event names a user or plugin may listen for via
+ * `import.meta.hot.on()`. Phase 7.0 v0.1 emits the first 4; the rest are
+ * Phase 7.1+ additions.
+ */
+export type HMREventName =
+  | "vite:beforeUpdate"
+  | "vite:afterUpdate"
+  | "vite:beforeFullReload"
+  | "vite:error"
+  | "vite:beforePrune"         // 7.1
+  | "vite:invalidate"          // 7.1
+  | "vite:ws:disconnect"       // 7.1
+  | "vite:ws:connect";         // 7.1
+
+// ============================================
+// Runtime `import.meta.hot` — Mandu subset
+// ============================================
+
+/**
+ * Runtime surface exposed as `import.meta.hot` in user/framework code.
+ *
+ * Phase 7.0 v0.1 supports:
+ *   - accept (self, self+cb, dep+cb)
+ *   - dispose
+ *   - data
+ *   - invalidate
+ *   - on (4 built-in events)
+ *
+ * Deferred to Phase 7.1+:
+ *   - accept([deps], cb)
+ *   - prune
+ *   - send, off
+ *   - custom events
+ *   - decline (legacy — we treat it as accept() no-op if anyone calls it)
+ *
+ * Design constraint: the `import.meta.hot.accept(` string must appear in
+ * the user's source verbatim for the bundler to recognize it as an HMR
+ * boundary (same static-analysis rule Vite enforces).
+ */
+export interface ManduHot {
+  /**
+   * Per-module state preserved across HMR updates. `data` is carried over
+   * when a module is hot-replaced; assign fields onto it, don't reassign
+   * the object.
+   */
+  readonly data: Record<string, unknown>;
+
+  /**
+   * Self-accept the module. Two overloads:
+   *   - `accept()` — no callback. The importer's `accept` runs instead.
+   *   - `accept(cb)` — receive the new module namespace.
+   */
+  accept(cb?: (newModule: unknown) => void): void;
+
+  /**
+   * Accept an update to a dependency path. The path must be a string
+   * literal at the call site (static analysis requirement).
+   */
+  accept(dep: string, cb: (newDep: unknown) => void): void;
+
+  /**
+   * Register a cleanup to run immediately before this module is replaced.
+   * The passed callback receives `data` so you can stash state.
+   */
+  dispose(cb: (data: Record<string, unknown>) => void): void;
+
+  /**
+   * Bail out of the current accept cycle and propagate the update to
+   * importers — used when the new module is incompatible with the old
+   * one (e.g. breaking API change).
+   */
+  invalidate(message?: string): void;
+
+  /**
+   * Subscribe to Vite-compatible lifecycle events.
+   */
+  on(event: HMREventName, cb: (payload: unknown) => void): void;
+}
+
+/**
+ * Per-module HMR context factory — what `createHMRClientScript` (Agent C)
+ * returns. The bundler rewrites `import.meta.hot` to a call that returns
+ * one of these.
+ */
+export interface ManduHotContextFactory {
+  (moduleUrl: string): ManduHot;
+}
+
+// ============================================
+// Replay (B8)
+// ============================================
+
+/**
+ * A broadcast envelope kept in the server's replay buffer. When a client
+ * reconnects with `?since=<id>` on the WS URL, the server re-sends every
+ * envelope with `id > since` so nothing is lost across short dropouts.
+ *
+ * The buffer is a bounded ring — `MAX_REPLAY_BUFFER` entries. Anything
+ * older is dropped, and reconnecting clients with a too-old `since` are
+ * forced to a `full-reload` (the safe fallback).
+ */
+export interface HMRReplayEnvelope {
+  /** Monotonically increasing per-server-boot. Resets to 0 on restart. */
+  id: number;
+  /** Unix ms when broadcast was queued. */
+  timestamp: number;
+  /** The payload that was / will be sent. */
+  payload: ViteHMRPayload;
+}
+
+/** Bounded buffer size. Anything older than this is pruned. */
+export const MAX_REPLAY_BUFFER = 128;
+
+/** "Missed too much — full reload" threshold in ms. */
+export const REPLAY_MAX_AGE_MS = 60_000;
+
+// ============================================
+// Coalesced file change (B2 + B6)
+// ============================================
+
+/**
+ * A batched change produced by Agent A's per-file debounce + Set-based
+ * `pendingBuildSet`. The rebuild path consumes one of these per tick, not
+ * one per raw fs event — this is the fix for B2 (single-slot drop) and B6
+ * (global single timer).
+ *
+ * `kind` categorizes the changes so the rebuild path can short-circuit
+ * ("mixed" → fall through to common-dir rebuild; "islands-only" → skip
+ * framework bundles).
+ */
+export interface CoalescedChange {
+  /** Absolute, normalized paths. No duplicates. */
+  files: readonly string[];
+  /** Earliest raw fs event timestamp (Date.now()). */
+  firstSeenAt: number;
+  /** Latest raw fs event timestamp. */
+  lastSeenAt: number;
+  /**
+   * Categorical summary derived from path classification. Pre-computed so
+   * the rebuild path doesn't re-scan the file list.
+   */
+  kind:
+    | "islands-only"            // *.client.tsx / *.island.tsx only
+    | "ssr-only"                // page.tsx / layout.tsx / slot.ts only
+    | "common-dir"              // src/** changes (may fan out to any route)
+    | "css-only"                // *.css only
+    | "api-only"                // route.ts (API)
+    | "config-reload"           // mandu.config.ts / .env — server restart
+    | "resource-regen"          // *.resource.ts / *.contract.ts — code-gen
+    | "mixed";                  // more than one category
+}
+
+// ============================================
+// Scenario matrix re-export for cross-module use
+// ============================================
+
+/**
+ * Re-exported so consumers can `import { ... } from "../bundler/hmr-types"`
+ * without a second import line. The canonical definitions live in
+ * `./scenario-matrix.ts` to keep this file logic-free.
+ */
+export type { ProjectForm, ChangeKind, ScenarioCell } from "./scenario-matrix";