ruact 0.0.7 → 0.0.8

data/vendor/javascript/ruact-server-functions-runtime/index.js

@@ -14,9 +14,11 @@
 // enforces). Reads are CSRF-free (GET semantics).
 //
 // The export surface (`_makeServerFunction`, `_makeQuery`, `useQuery`,
-// `revalidate`, `configureRuactRuntime`, `RuactActionError`) and the
-// `"ruact/server-functions-runtime"` import path are part of the locked API —
-// do NOT change without coordinated codegen + Vite-plugin updates.
+// `revalidate`, `withRefresh`, `configureRuactRuntime`, `RuactActionError`) and
+// the `"ruact/server-functions-runtime"` import path are part of the locked API —
+// do NOT change without coordinated codegen + Vite-plugin updates. (Story 15.6
+// added `withRefresh` — a runtime-only wrapper; it is NOT re-exported through the
+// generated `.ruact/server-functions.ts` barrel, so codegen output is unchanged.)
 
 // Story 9.5 — `useQuery` is a React hook, so the runtime now depends on React.
 // React is declared as a `peerDependency` (every host already has it; the
@@ -33,8 +35,16 @@ const RUNTIME_VERSION = 1;
 // them; instead, hosts call `configureRuactRuntime` once at app boot
 // to register a headers-producing function. The function runs on
 // every fetch so dynamic tokens (refreshed at runtime) are picked up.
+// Story 15.6 (FR110) — `autoRevalidate` is the app-wide default for the
+// auto-revalidate opt-in: when `true`, every successful, NON-redirecting mutation
+// (`_makeServerFunction` accessor) `await`s an in-place Flight refresh of the
+// current path (via the existing `revalidate()`) BEFORE resolving with the
+// action's JSON result. Default `false` → today's behavior, byte-identical. A
+// per-call `withRefresh(accessor)` wrapper forces the refresh for a single call
+// and WINS over this global (D5: per-call explicit beats the global default).
 const runtimeOptions = {
   defaultHeaders: null,
+  autoRevalidate: false,
 };
 export function configureRuactRuntime(options) {
   if (options && Object.prototype.hasOwnProperty.call(options, "defaultHeaders")) {
@@ -47,6 +57,15 @@ export function configureRuactRuntime(options) {
       );
     }
   }
+  if (options && Object.prototype.hasOwnProperty.call(options, "autoRevalidate")) {
+    const value = options.autoRevalidate;
+    if (typeof value !== "boolean") {
+      throw new TypeError(
+        "configureRuactRuntime: autoRevalidate must be a boolean",
+      );
+    }
+    runtimeOptions.autoRevalidate = value;
+  }
 }
 
 /**
@@ -101,12 +120,28 @@ export class RuactActionError extends Error {
  *     (`globalThis.__ruact_navigate`, `window.location.assign` fallback) and
  *     resolves `null`.
  *
+ * Story 15.6 (FR110) — auto-revalidate opt-in. When the call opts in — via the
+ * app-wide `configureRuactRuntime({ autoRevalidate: true })` default OR the
+ * per-call `withRefresh(accessor)` wrapper — a SUCCESSFUL, NON-redirecting
+ * mutation `await`s an in-place Flight refresh of the current path (the existing
+ * `revalidate()`) BEFORE the promise resolves, then resolves with the action's
+ * JSON result. This is pure client-side COMPOSITION of the two requests that
+ * already exist (POST-JSON mutation + GET-Flight refresh) — no new wire shape, no
+ * inbound Flight deserialization (serialize-only invariant intact). A `$redirect`
+ * WINS: the redirect is followed and the refresh is SKIPPED (refreshing the old
+ * path would be wrong). A failed mutation throws before the refresh runs, so no
+ * refresh happens. If the refresh is requested with no router installed, the
+ * descriptive `revalidate()` error surfaces (it is not swallowed).
+ *
  * @param {{ method: string, path: string, segments?: string[] }} descriptor
  * @returns {(arg1?: Record<string, unknown> | FormData, arg2?: FormData | Record<string, unknown>) => Promise<unknown>}
  */
 export function _makeServerFunction(descriptor) {
   const { method, path, segments = [] } = descriptor || {};
-  return async function ruactServerFunctionCall(...callArgs) {
+  // The core invoker takes the raw call-args plus a `refreshOverride`:
+  //   undefined → fall back to the app-wide `runtimeOptions.autoRevalidate`;
+  //   true/false → an explicit per-call decision that WINS over the global (D5).
+  const invoke = async function (callArgs, refreshOverride) {
     if (callArgs.length > 2) {
       throw new TypeError(
         `ruact server function ${method} ${path} called with ${callArgs.length} arguments — ` +
@@ -115,8 +150,61 @@ export function _makeServerFunction(descriptor) {
     }
     const args = pickWirePayload(callArgs);
     const url = interpolatePath(path, segments, args);
+    // AC4 — a failed mutation throws HERE, before any refresh is sequenced.
     const parsed = await ruactInvoke({ method, url, args, label: path });
-    return followRedirectIfPresent(parsed);
+    const { value, redirected } = followRedirect(parsed);
+    // AC2 — redirect wins: the destination already re-renders; skip the refresh.
+    if (redirected) return value;
+    const refresh =
+      refreshOverride === undefined ? runtimeOptions.autoRevalidate === true : refreshOverride === true;
+    if (refresh) {
+      // AC1 — refresh the current path in place BEFORE resolving. AC5 — if no
+      // router is installed, `revalidate()`'s descriptive error surfaces here
+      // (D3: a mutation that succeeded but whose refresh rejects rejects the
+      // promise — consistent with `revalidate()`'s loud-by-default stance).
+      await revalidate();
+    }
+    return value;
+  };
+  const accessor = function ruactServerFunctionCall(...callArgs) {
+    return invoke(callArgs, undefined);
+  };
+  // Stash the core invoker on the accessor (non-enumerable) so `withRefresh` can
+  // force a refresh for a single call WITHOUT the codegen emitting a different
+  // accessor shape — the generated `.ruact/server-functions.ts` stays byte-
+  // identical (AC6). Keyed by a module-private Symbol so host code can't collide.
+  Object.defineProperty(accessor, REFRESH_INVOKER, { value: invoke, enumerable: false });
+  return accessor;
+}
+
+// Story 15.6 (FR110) — module-private handle used by `withRefresh` to reach a
+// server-function accessor's core invoker (see `_makeServerFunction`).
+const REFRESH_INVOKER = Symbol("ruactRefreshInvoker");
+
+/**
+ * Story 15.6 (FR110) — per-call auto-revalidate wrapper. Wraps a generated
+ * server-function accessor and returns a NEW accessor that forces the in-place
+ * Flight refresh after a successful, non-redirecting call — regardless of the
+ * app-wide `autoRevalidate` default (D5: per-call explicit wins). Runtime-only:
+ * it does not change the codegen or the wire.
+ *
+ *   import { createPost } from "@/.ruact/server-functions";
+ *   import { withRefresh } from "ruact/server-functions-runtime";
+ *   await withRefresh(createPost)(formData); // mutation + refresh in one await
+ *
+ * @param {Function} accessor A `_makeServerFunction`-produced accessor.
+ * @returns {(...args: unknown[]) => Promise<unknown>} A refreshing accessor.
+ */
+export function withRefresh(accessor) {
+  const invoke = typeof accessor === "function" ? accessor[REFRESH_INVOKER] : undefined;
+  if (typeof invoke !== "function") {
+    throw new TypeError(
+      "ruact withRefresh() expects a server-function accessor produced by the ruact codegen " +
+        "(imported from @/.ruact/server-functions)",
+    );
+  }
+  return function ruactRefreshingCall(...callArgs) {
+    return invoke(callArgs, true);
   };
 }
 
@@ -519,6 +607,15 @@ function readSegment(args, seg) {
 // `{ "$redirect": "<path>" }`; follow it via the router handoff and resolve
 // `null` (consistent with the 204→null contract).
 function followRedirectIfPresent(parsed) {
+  return followRedirect(parsed).value;
+}
+
+// Story 15.6 — the same follow logic, but reporting WHETHER a redirect was
+// followed as an explicit boolean. Auto-revalidate needs to distinguish "a
+// redirect was followed → skip the refresh" from "the action genuinely resolved
+// `null`/204 → still refresh" — inferring redirect from `value === null` would
+// wrongly skip the refresh after an ordinary empty-body mutation.
+function followRedirect(parsed) {
   if (
     parsed &&
     typeof parsed === "object" &&
@@ -526,9 +623,9 @@ function followRedirectIfPresent(parsed) {
     typeof parsed.$redirect === "string"
   ) {
     navigateTo(parsed.$redirect);
-    return null;
+    return { value: null, redirected: true };
   }
-  return parsed;
+  return { value: parsed, redirected: false };
 }
 
 function navigateTo(target) {

data/vendor/javascript/ruact-server-functions-runtime/index.test.mjs

@@ -15,6 +15,7 @@ import {
   RuactActionError,
   configureRuactRuntime,
   revalidate,
+  withRefresh,
 } from "./index.js";
 
 // Helper — a route-driven accessor targeting `POST /posts` (the canonical
@@ -822,3 +823,175 @@ describe("Story 9.3 — _makeServerFunction (route-driven, real path+verb)", ()
     expect(result).toEqual({ post: { id: 1 }, $redirect: 42 });
   });
 });
+
+// =============================================================================
+// Story 15.6 (FR110) — auto-revalidate opt-in: one await = mutation + refresh
+// =============================================================================
+
+describe("Story 15.6 — auto-revalidate opt-in", () => {
+  let originalRevalidate;
+  let originalNavigate;
+  let originalLocation;
+  let originalWindow;
+
+  beforeEach(() => {
+    originalRevalidate = globalThis.__ruact_revalidate;
+    originalNavigate = globalThis.__ruact_navigate;
+    originalLocation = globalThis.location;
+    originalWindow = globalThis.window;
+    globalThis.location = { pathname: "/posts", search: "?page=2" };
+  });
+
+  afterEach(() => {
+    // Reset the app-wide default so a leaked `autoRevalidate: true` can't bleed
+    // into the un-opted-in byte-parity tests elsewhere in the suite.
+    configureRuactRuntime({ autoRevalidate: false });
+    if (originalRevalidate === undefined) delete globalThis.__ruact_revalidate;
+    else globalThis.__ruact_revalidate = originalRevalidate;
+    globalThis.__ruact_navigate = originalNavigate;
+    if (originalLocation === undefined) {
+      // jsdom / browser env — leave the real `location` alone
+    } else {
+      globalThis.location = originalLocation;
+    }
+    globalThis.window = originalWindow;
+  });
+
+  // (a) request-composition order — POST then Flight refresh, in that order,
+  // resolves with the action's JSON result.
+  it("global default: refreshes the current path AFTER the mutation and resolves the JSON result", async () => {
+    const order = [];
+    mockFetchOk({ id: 7 });
+    const fetchSpy = globalThis.fetch;
+    fetchSpy.mockImplementation(async () => {
+      order.push("fetch");
+      return {
+        ok: true,
+        status: 200,
+        headers: { get: (n) => (n.toLowerCase() === "content-type" ? "application/json" : null) },
+        text: vi.fn().mockResolvedValue(JSON.stringify({ id: 7 })),
+        json: vi.fn().mockResolvedValue({ id: 7 }),
+      };
+    });
+    const revalidateSpy = vi.fn(async () => {
+      order.push("revalidate");
+    });
+    globalThis.__ruact_revalidate = revalidateSpy;
+    configureRuactRuntime({ autoRevalidate: true });
+
+    const createPost = _makeServerFunction({ method: "POST", path: "/posts", segments: [] });
+    const result = await createPost({ title: "x" });
+
+    expect(order).toEqual(["fetch", "revalidate"]);
+    expect(revalidateSpy).toHaveBeenCalledWith("/posts?page=2");
+    expect(result).toEqual({ id: 7 });
+  });
+
+  it("per-call withRefresh: forces the refresh even when the global default is OFF", async () => {
+    mockFetchOk({ id: 1 });
+    const revalidateSpy = vi.fn().mockResolvedValue(undefined);
+    globalThis.__ruact_revalidate = revalidateSpy;
+    configureRuactRuntime({ autoRevalidate: false });
+
+    const createPost = _makeServerFunction({ method: "POST", path: "/posts", segments: [] });
+    const result = await withRefresh(createPost)({ title: "x" });
+
+    expect(revalidateSpy).toHaveBeenCalledWith("/posts?page=2");
+    expect(result).toEqual({ id: 1 });
+  });
+
+  it("refreshes after a genuine null/204 result (not misread as a redirect)", async () => {
+    mockFetchOk("", { status: 204, contentType: "text/plain" });
+    const revalidateSpy = vi.fn().mockResolvedValue(undefined);
+    globalThis.__ruact_revalidate = revalidateSpy;
+
+    const createPost = _makeServerFunction({ method: "POST", path: "/posts", segments: [] });
+    const result = await withRefresh(createPost)({});
+
+    expect(revalidateSpy).toHaveBeenCalledTimes(1);
+    expect(result).toBeNull();
+  });
+
+  // (b) error propagation — a failed mutation rejects and issues NO refresh.
+  it("mutation failure propagates and does NOT refresh (refresh sequenced after success)", async () => {
+    mockFetchError(422, JSON.stringify({ error: "invalid" }));
+    const revalidateSpy = vi.fn().mockResolvedValue(undefined);
+    globalThis.__ruact_revalidate = revalidateSpy;
+    configureRuactRuntime({ autoRevalidate: true });
+
+    const createPost = _makeServerFunction({ method: "POST", path: "/posts", segments: [] });
+
+    await expect(createPost({ title: "" })).rejects.toMatchObject({
+      name: "RuactActionError",
+      status: 422,
+    });
+    expect(revalidateSpy).not.toHaveBeenCalled();
+  });
+
+  // (c) redirect-wins — a $redirect follows the redirect and issues NO refresh.
+  it("redirect wins: follows the $redirect, resolves null, and SKIPS the refresh", async () => {
+    mockFetchOk({ $redirect: "/posts/1" });
+    const navSpy = vi.fn();
+    globalThis.__ruact_navigate = navSpy;
+    const revalidateSpy = vi.fn().mockResolvedValue(undefined);
+    globalThis.__ruact_revalidate = revalidateSpy;
+    configureRuactRuntime({ autoRevalidate: true });
+
+    const createPost = _makeServerFunction({ method: "POST", path: "/posts", segments: [] });
+    const result = await createPost({ title: "x" });
+
+    expect(navSpy).toHaveBeenCalledWith("/posts/1");
+    expect(result).toBeNull();
+    expect(revalidateSpy).not.toHaveBeenCalled();
+  });
+
+  // (d) no-router — the descriptive revalidate() error surfaces (not swallowed).
+  it("no router installed: surfaces the descriptive revalidate() error", async () => {
+    mockFetchOk({ id: 1 });
+    if ("__ruact_revalidate" in globalThis) delete globalThis.__ruact_revalidate;
+    configureRuactRuntime({ autoRevalidate: true });
+
+    const createPost = _makeServerFunction({ method: "POST", path: "/posts", segments: [] });
+
+    await expect(createPost({ title: "x" })).rejects.toThrow(
+      /ruact: revalidate\(\) called but no router is installed/,
+    );
+  });
+
+  it("D3: a successful mutation whose refresh REJECTS rejects the returned promise", async () => {
+    mockFetchOk({ id: 9 });
+    const revalidateSpy = vi.fn().mockRejectedValue(new Error("Flight refresh failed"));
+    globalThis.__ruact_revalidate = revalidateSpy;
+
+    const createPost = _makeServerFunction({ method: "POST", path: "/posts", segments: [] });
+
+    await expect(withRefresh(createPost)({ title: "x" })).rejects.toThrow("Flight refresh failed");
+    expect(revalidateSpy).toHaveBeenCalledTimes(1);
+  });
+
+  // (e) un-opted-in is byte-identical to today: exactly one fetch, no refresh.
+  it("un-opted-in call is byte-identical: one fetch, no refresh", async () => {
+    mockFetchOk({ id: 1 });
+    const revalidateSpy = vi.fn().mockResolvedValue(undefined);
+    globalThis.__ruact_revalidate = revalidateSpy;
+    // global default stays OFF (reset in afterEach), no withRefresh wrapper.
+
+    const createPost = _makeServerFunction({ method: "POST", path: "/posts", segments: [] });
+    const result = await createPost({ title: "x" });
+
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+    expect(revalidateSpy).not.toHaveBeenCalled();
+    expect(result).toEqual({ id: 1 });
+  });
+
+  it("withRefresh throws a descriptive TypeError for a non-accessor argument", () => {
+    expect(() => withRefresh(() => {})).toThrow(/server-function accessor produced by the ruact codegen/);
+    expect(() => withRefresh(null)).toThrow(TypeError);
+  });
+
+  it("configureRuactRuntime rejects a non-boolean autoRevalidate", () => {
+    expect(() => configureRuactRuntime({ autoRevalidate: "yes" })).toThrow(
+      /autoRevalidate must be a boolean/,
+    );
+  });
+});

data/vendor/javascript/vite-plugin-ruact/type-tests/auto-revalidate.test-d.ts

@@ -0,0 +1,25 @@
+// Story 15.6 (FR110) — type-level test for the auto-revalidate opt-in surface.
+// Proves (a) `configureRuactRuntime` accepts the new `autoRevalidate?: boolean`
+// key alongside `defaultHeaders`, and (b) `withRefresh` preserves the wrapped
+// accessor's call signature (so `withRefresh(createPost)` is callable exactly
+// like `createPost`). Runtime-only: this surface is NOT emitted by the codegen,
+// so there is no byte-parity fixture to regenerate.
+
+import { _makeServerFunction, configureRuactRuntime, withRefresh } from "ruact/server-functions-runtime";
+
+// (a) the app-wide default key type-checks (and stays optional).
+configureRuactRuntime({ autoRevalidate: true });
+configureRuactRuntime({ autoRevalidate: false, defaultHeaders: { Authorization: "Bearer x" } });
+configureRuactRuntime({ defaultHeaders: null });
+
+// A non-boolean autoRevalidate is a type error.
+// @ts-expect-error autoRevalidate must be a boolean
+configureRuactRuntime({ autoRevalidate: "yes" });
+
+// (b) withRefresh preserves the accessor call signature.
+const createPost = _makeServerFunction({ method: "POST", path: "/posts", segments: [] });
+const createPostRefreshing = withRefresh(createPost);
+
+// Callable at the same shapes as the underlying accessor.
+void createPostRefreshing({ title: "x" });
+void createPostRefreshing();

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruact
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.8
 platform: ruby
 authors:
 - Luiz Garcia
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-30 00:00:00.000000000 Z
+date: 2026-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -46,6 +46,7 @@ files:
 - docs/internal/README.md
 - docs/internal/decisions/server-functions-api.md
 - lib/generators/ruact/install/install_generator.rb
+- lib/generators/ruact/install/templates/AGENTS.md.tt
 - lib/generators/ruact/install/templates/Procfile.dev.tt
 - lib/generators/ruact/install/templates/dev.tt
 - lib/generators/ruact/install/templates/initializer.rb.tt
@@ -102,6 +103,7 @@ files:
 - lib/ruact/server_functions/error_payload.rb
 - lib/ruact/server_functions/error_rendering.rb
 - lib/ruact/server_functions/error_suggestion.rb
+- lib/ruact/server_functions/introspection.rb
 - lib/ruact/server_functions/name_bridge.rb
 - lib/ruact/server_functions/query_context.rb
 - lib/ruact/server_functions/query_dispatch.rb
@@ -112,6 +114,11 @@ files:
 - lib/ruact/server_functions/validation_errors.rb
 - lib/ruact/signed_references.rb
 - lib/ruact/string_distance.rb
+- lib/ruact/testing.rb
+- lib/ruact/testing/component_query.rb
+- lib/ruact/testing/flight_extractor.rb
+- lib/ruact/testing/flight_structure_diff.rb
+- lib/ruact/testing/flight_wire_parser.rb
 - lib/ruact/validation_errors_collector.rb
 - lib/ruact/version.rb
 - lib/ruact/view_helper.rb
@@ -176,6 +183,7 @@ files:
 - spec/ruact/server_functions/codegen_spec.rb
 - spec/ruact/server_functions/error_payload_spec.rb
 - spec/ruact/server_functions/error_suggestion_spec.rb
+- spec/ruact/server_functions/introspection_spec.rb
 - spec/ruact/server_functions/name_bridge_spec.rb
 - spec/ruact/server_functions/query_context_spec.rb
 - spec/ruact/server_functions/query_source_spec.rb
@@ -189,6 +197,9 @@ files:
 - spec/ruact/server_upload_request_spec.rb
 - spec/ruact/signed_references_spec.rb
 - spec/ruact/string_distance_spec.rb
+- spec/ruact/tasks_json_introspection_spec.rb
+- spec/ruact/testing/have_ruact_component_spec.rb
+- spec/ruact/testing/no_production_load_spec.rb
 - spec/ruact/validation_errors_spec.rb
 - spec/ruact/view_helper_spec.rb
 - spec/spec_helper.rb
@@ -218,6 +229,7 @@ files:
 - vendor/javascript/vite-plugin-ruact/tsconfig.json
 - vendor/javascript/vite-plugin-ruact/tsconfig.scaffold-agnostic.json
 - vendor/javascript/vite-plugin-ruact/tsconfig.scaffold.json
+- vendor/javascript/vite-plugin-ruact/type-tests/auto-revalidate.test-d.ts
 - vendor/javascript/vite-plugin-ruact/type-tests/emitted-module.test-d.ts
 - vendor/javascript/vite-plugin-ruact/type-tests/scaffold/PostDeleteDialog.tsx
 - vendor/javascript/vite-plugin-ruact/type-tests/scaffold/PostForm.tsx