every-plugin 2.10.1 → 3.0.0-rc.10

package/src/build/ui/stubs.ts

@@ -0,0 +1,103 @@
+/**
+ * The core ui's generated bootstrap stubs — the mechanical files an app must
+ * never author or edit (ADR 0023): the web MF entry, the `./Hydrate`
+ * bootstrap, the SSR router module, the `./compose` expose, and the ambient
+ * globals. Emitted into the ui source root by the framework's code-artifact
+ * generation pass, regenerated from the installed package version, and
+ * gitignored (`*.gen.*`) — never synced, never hand-maintained.
+ *
+ * The generated hydrate/SSR stubs wire the app's AUTHORED seams into the
+ * framework machinery: the router policy factory (`src/router.tsx`) and the
+ * app override exports from `src/app.ts` (`apiConnectionError`, `appLocale`).
+ * The seam files are scaffolded once by `bos init` and owned by the app; the
+ * stubs themselves carry zero app-specific content.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export const CORE_UI_STUBS: Record<string, string> = {
+  "src/entry.gen.ts": `// GENERATED FILE — do not edit. Regenerated from the installed framework version
+// by \`bos dev\` / \`bos build\` / \`bos typecheck\` (gitignored).
+import "./styles.css";
+import { runEntry } from "everything-dev/ui/entry";
+
+runEntry(() => import("./hydrate.gen"));
+`,
+  "src/hydrate.gen.tsx": `// GENERATED FILE — do not edit. Regenerated from the installed framework version
+// by \`bos dev\` / \`bos build\` / \`bos typecheck\` (gitignored).
+import "./styles.css";
+import { hydrate as coreHydrate } from "everything-dev/ui/hydrate";
+import { apiConnectionError } from "./app";
+import { createQueryClient, createRouter } from "./router";
+
+export function hydrate() {
+  return coreHydrate({
+    routeConfig: () => import("./routeConfig.gen"),
+    manifest: () => import("./manifest.gen.json"),
+    createRouter,
+    createQueryClient,
+    apiConnectionError,
+  });
+}
+
+export default hydrate;
+`,
+  "src/router.server.gen.tsx": `// GENERATED FILE — do not edit. Regenerated from the installed framework version
+// by \`bos dev\` / \`bos build\` / \`bos typecheck\` (gitignored).
+import { createServerRouterModule } from "everything-dev/ui/router-server";
+import { appLocale } from "./app";
+import { createQueryClient, createRouter } from "./router";
+import { routeTree } from "./routeTree.gen";
+
+const routerModule = createServerRouterModule({
+  defaultRouteTree: routeTree,
+  createRouter,
+  createQueryClient,
+  locale: appLocale,
+});
+
+export default routerModule;
+`,
+  "src/compose.gen.ts": `// GENERATED FILE — do not edit. Regenerated from the installed framework version
+// by \`bos dev\` / \`bos build\` / \`bos typecheck\` (gitignored).
+export type {
+  ConstructedTree,
+  ConstructInput,
+  ConstructPluginRef,
+  GateUser,
+  HostContext,
+  NavManifest,
+  PluginManifest,
+  ResolvedPlugin,
+  RouteConfigModule,
+  RouteOptionsBundle,
+} from "everything-dev/ui/manifest";
+export {
+  CORE_UI_PLUGIN_KEY,
+  ComposePayloadSchema,
+  constructTree,
+} from "everything-dev/ui/manifest";
+`,
+  "src/globals.gen.ts": `// GENERATED FILE — do not edit. Regenerated from the installed framework version
+// by \`bos dev\` / \`bos build\` / \`bos typecheck\` (gitignored).
+/// <reference types="@rsbuild/core/types" />
+`,
+};
+
+/**
+ * Emits the stub set into the ui source root. Returns the stub paths whose
+ * content actually changed (empty when everything is already current) — the
+ * same-content suppression keeps dev watchers from regen loops.
+ */
+export function emitCoreUiStubs(uiRoot: string): string[] {
+  const written: string[] = [];
+  for (const [relPath, content] of Object.entries(CORE_UI_STUBS)) {
+    const fullPath = join(uiRoot, relPath);
+    if (existsSync(fullPath) && readFileSync(fullPath, "utf-8") === content) continue;
+    mkdirSync(dirname(fullPath), { recursive: true });
+    writeFileSync(fullPath, content);
+    written.push(relPath);
+  }
+  return written;
+}

package/src/cli.ts

@@ -0,0 +1,100 @@
+import { spawn } from "node:child_process";
+import { generateContractTypes } from "./build/contract-types";
+import { ensureGeneratedRspackConfig } from "./build/rspack/generated-config";
+import {
+  ensureGeneratedCoreUiRsbuildConfig,
+  ensureGeneratedUiRsbuildConfig,
+  hasCoreUiWorkspace,
+} from "./build/ui/generated-config";
+
+function run(
+  cmd: string,
+  args: string[],
+  env: Record<string, string | undefined> = {},
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      stdio: "inherit",
+      env: { ...process.env, ...env },
+      shell: process.platform === "win32",
+    });
+    child.on("exit", (code) =>
+      code === 0
+        ? resolve()
+        : reject(new Error(`${cmd} ${args.join(" ")} exited with code ${code}`)),
+    );
+    child.on("error", reject);
+  });
+}
+
+export async function emitContractTypes(): Promise<void> {
+  const status = await generateContractTypes();
+  if (status === "skipped") {
+    console.log("[every-plugin] No src/contract.ts — nothing to emit.");
+  } else {
+    console.log(`[every-plugin] Contract types ${status}.`);
+  }
+}
+
+/**
+ * Workspace-form core ui build surface — the /api model applied to the ui:
+ * the generated config (or a local rsbuild.config.ts override) drives
+ * rsbuild; extra args pass through (`--environment web|node`).
+ */
+async function runCoreUi(args: string[]): Promise<void> {
+  const generatedConfig = ensureGeneratedCoreUiRsbuildConfig();
+  const [command = "build", ...rest] = args;
+  const configArgs = generatedConfig ? ["--config", generatedConfig] : [];
+  await run("rsbuild", [command, ...configArgs, ...rest], {});
+}
+
+async function runRspack(): Promise<void> {
+  const generatedConfig = ensureGeneratedRspackConfig();
+
+  const args = generatedConfig ? ["build", "--config", generatedConfig] : ["build"];
+  await run("rspack", args, {});
+
+  const uiConfig = ensureGeneratedUiRsbuildConfig(process.cwd());
+  if (uiConfig) {
+    console.log("[every-plugin] Building folder-form ui source…");
+    await run("rsbuild", ["build", "--config", uiConfig], {});
+  }
+}
+
+export function runCliCommand(raw: string, args: string[] = []): Promise<void> {
+  const command = raw.replace(/=.*/, "");
+  if (command === "dev") process.env.BOS_DEV_SERVER = "1";
+  // The core ui workspace form routes build/dev/preview through rsbuild;
+  // plugin workspaces keep the rspack/dev-server surface.
+  if (hasCoreUiWorkspace()) {
+    switch (command) {
+      case "build":
+        return runCoreUi(["build", ...args]);
+      case "preview":
+        return runCoreUi(["preview", ...args]);
+      case "dev":
+        return runCoreUi(["dev", ...args]);
+      default:
+        return Promise.reject(
+          new Error(`Unknown every-plugin command for a core ui workspace: ${raw}`),
+        );
+    }
+  }
+  switch (command) {
+    case "types":
+      return emitContractTypes();
+    case "build":
+    case "deploy":
+      return runRspack();
+    case "dev":
+      return (async () => {
+        const { startPluginDevServer } = await import("./dev/serve");
+        await startPluginDevServer();
+        return new Promise<void>(() => {});
+      })();
+    default:
+      return Promise.reject(
+        new Error(`Unknown every-plugin command: ${raw} (expected dev|types|build|deploy)`),
+      );
+  }
+}

package/src/client.ts

@@ -0,0 +1,111 @@
+import { createORPCClient, onError } from "@orpc/client";
+import { RPCLink } from "@orpc/client/fetch";
+import type { ContractRouterClient, RouterContract } from "@orpc/contract";
+
+export type RpcConnectionErrorCopy = () => { title: string; description: string };
+
+export interface RpcClientConfig {
+  hostUrl: string;
+  path: `/${string}`;
+  connectionError?: RpcConnectionErrorCopy;
+}
+
+const RATE_LIMIT_MAX_RETRIES = 3;
+const RATE_LIMIT_RETRY_CAP_MS = 2_000;
+const browserClients = new Map<string, unknown>();
+type FetchInput = Parameters<typeof fetch>[0];
+
+async function fetchWithRateLimitRetry(
+  fetchUrl: FetchInput,
+  options?: RequestInit,
+): Promise<Response> {
+  let response = await fetch(fetchUrl, options);
+  for (let attempt = 1; attempt <= RATE_LIMIT_MAX_RETRIES && response.status === 429; attempt++) {
+    const retryAfterSeconds = Number(response.headers.get("retry-after"));
+    const delay =
+      Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0
+        ? Math.min(retryAfterSeconds * 1000, RATE_LIMIT_RETRY_CAP_MS)
+        : 100 * attempt;
+    await new Promise((resolve) => setTimeout(resolve, delay));
+    response = await fetch(fetchUrl, options);
+  }
+
+  return response;
+}
+
+function createRpcLink(config: RpcClientConfig, headers?: Headers) {
+  return new RPCLink({
+    origin: config.hostUrl,
+    url: config.path,
+    interceptors: [
+      onError((error: unknown) => {
+        const browserWindow = (globalThis as { window?: unknown }).window;
+        if (typeof browserWindow === "undefined") {
+          return;
+        }
+
+        if (error && typeof error === "object" && "message" in error) {
+          const message = String(error.message).toLowerCase();
+          if (
+            message.includes("fetch") ||
+            message.includes("network") ||
+            message.includes("failed to fetch")
+          ) {
+            void import("sonner")
+              .then(({ toast }) => {
+                const message = config.connectionError?.() ?? {
+                  title: "Unable to connect to API",
+                  description: "The API is currently unavailable. Please try again later.",
+                };
+                toast.error(message.title, {
+                  id: "api-connection-error",
+                  description: message.description,
+                });
+              })
+              .catch(() => {});
+          }
+        }
+      }),
+    ],
+    fetch(fetchUrl: FetchInput, options?: RequestInit) {
+      return fetchWithRateLimitRetry(fetchUrl, {
+        ...options,
+        credentials: "include",
+        headers: headers
+          ? { ...Object.fromEntries(headers), ...(options?.headers as Record<string, string>) }
+          : options?.headers,
+      });
+    },
+  });
+}
+
+function buildRpcClient<T extends RouterContract>(
+  config: RpcClientConfig,
+  headers?: Headers,
+): ContractRouterClient<T> {
+  if (!config.hostUrl) {
+    throw new Error("Missing runtime host URL");
+  }
+
+  return createORPCClient(createRpcLink(config, headers)) as ContractRouterClient<T>;
+}
+
+export function createRpcClient<T extends RouterContract = RouterContract>(
+  config: RpcClientConfig,
+  headers?: Headers,
+): ContractRouterClient<T> {
+  const browserWindow = (globalThis as { window?: unknown }).window;
+  if (typeof browserWindow !== "undefined" && !headers) {
+    const key = `${config.hostUrl}${config.path}`;
+    const memoized = browserClients.get(key);
+    if (memoized) {
+      return memoized as ContractRouterClient<T>;
+    }
+
+    const client = buildRpcClient<T>(config, headers);
+    browserClients.set(key, client);
+    return client;
+  }
+
+  return buildRpcClient<T>(config, headers);
+}

package/src/dev/host.ts

@@ -0,0 +1,235 @@
+import type http from "node:http";
+import { createServer } from "node:http";
+
+const corsHeaders = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS",
+  "Access-Control-Allow-Headers": "X-Requested-With, content-type, Authorization",
+};
+
+const applyCorsHeaders = (res: http.ServerResponse) => {
+  Object.entries(corsHeaders).forEach(([key, value]) => {
+    res.setHeader(key, value);
+  });
+};
+
+const sendJson = (res: http.ServerResponse, status: number, body: unknown) => {
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json; charset=utf-8");
+  res.end(JSON.stringify(body));
+};
+
+const sendText = (res: http.ServerResponse, status: number, text: string) => {
+  res.statusCode = status;
+  res.setHeader("content-type", "text/plain; charset=utf-8");
+  res.end(text);
+};
+
+const pathnameOf = (req: http.IncomingMessage): string =>
+  ((req.url ?? "/").split("?")[0] ?? "/").replace(/\/+$/, "") || "/";
+
+const toWebRequest = (req: http.IncomingMessage, port: number): Request => {
+  const url = `http://localhost:${port}${req.url}`;
+  return new Request(url, {
+    method: req.method,
+    headers: req.headers,
+    body: req.method !== "GET" && req.method !== "HEAD" ? req : undefined,
+    duplex: req.method !== "GET" && req.method !== "HEAD" ? "half" : undefined,
+  } as RequestInit);
+};
+
+const buildHostContext = (
+  effectContext: unknown,
+  webRequest: Request,
+  cachedRawBodyRef: { value: string | null },
+) => {
+  const rawClone =
+    webRequest.method === "GET" || webRequest.method === "HEAD" ? null : webRequest.clone();
+
+  return {
+    reqHeaders: webRequest.headers,
+    "effect/context": effectContext,
+    getRawBody: async (): Promise<string> => {
+      if (cachedRawBodyRef.value !== null) return cachedRawBodyRef.value;
+      if (!rawClone) {
+        cachedRawBodyRef.value = "";
+        return cachedRawBodyRef.value;
+      }
+      cachedRawBodyRef.value = await rawClone.text();
+      return cachedRawBodyRef.value;
+    },
+  };
+};
+
+export interface DirectModuleHostHandler {
+  handle(
+    request: Request,
+    options: { prefix: string; context: unknown },
+  ): Promise<{ response?: Response }>;
+}
+
+const handleOrpc = async (
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  handler: DirectModuleHostHandler,
+  prefix: string,
+  errorLabel: string,
+  effectContext: unknown,
+  port: number,
+) => {
+  try {
+    const webRequest = toWebRequest(req, port);
+    const cachedRawBodyRef = { value: null as string | null };
+    const result = await handler.handle(webRequest, {
+      prefix,
+      context: buildHostContext(effectContext, webRequest, cachedRawBodyRef),
+    });
+
+    if (result.response) {
+      res.statusCode = result.response.status;
+      result.response.headers.forEach((value: string, key: string) => {
+        res.setHeader(key, value);
+      });
+      const text = await result.response.text();
+      if (!res.getHeader("content-length")) {
+        res.setHeader("content-length", Buffer.byteLength(text).toString());
+      }
+      res.end(text);
+    } else {
+      sendText(res, 404, "Not Found");
+    }
+  } catch (error) {
+    console.error(`${errorLabel} error:`, error);
+    sendJson(res, 500, { error: (error as Error).message });
+  }
+};
+
+export interface DirectModuleHostHandlers {
+  rpc: DirectModuleHostHandler | null;
+  api: DirectModuleHostHandler | null;
+}
+
+export interface DirectModuleHostOptions {
+  name: string;
+  handlers: DirectModuleHostHandlers;
+  effectContext: unknown;
+  port?: number;
+  version?: string;
+  rpcPrefix?: `/${string}`;
+  apiPrefix?: `/${string}`;
+  staticHandler?:
+    | ((req: http.IncomingMessage, res: http.ServerResponse, next: () => void) => void)
+    | null;
+}
+
+export interface DirectModuleHostHandle {
+  port: number;
+  close: () => Promise<void>;
+}
+
+export async function startDirectModuleHost(
+  options: DirectModuleHostOptions,
+): Promise<DirectModuleHostHandle> {
+  const port = options.port ?? 0;
+  let resolvedPort = port;
+  const rpcPrefix = options.rpcPrefix ?? "/api/rpc";
+  const apiPrefix = options.apiPrefix ?? "/api";
+  const staticHandler = options.staticHandler ?? null;
+  const resolveEffectContext: () => unknown =
+    typeof options.effectContext === "function"
+      ? (options.effectContext as () => unknown)
+      : () => options.effectContext;
+
+  const server = createServer((req, res) => {
+    applyCorsHeaders(res);
+    const pathname = pathnameOf(req);
+
+    if (req.method === "OPTIONS") {
+      res.statusCode = 200;
+      res.end();
+      return;
+    }
+
+    if (pathname === "/" && (req.method === "GET" || req.method === "HEAD")) {
+      sendJson(res, 200, {
+        ok: true,
+        module: options.name,
+        version: options.version,
+        status: options.handlers.rpc ? "ready" : "loading",
+        endpoints: {
+          health: "/health",
+          docs: apiPrefix,
+          rpc: rpcPrefix,
+        },
+      });
+      return;
+    }
+
+    if (pathname === "/health" && (req.method === "GET" || req.method === "HEAD")) {
+      sendText(res, 200, "OK");
+      return;
+    }
+
+    if (pathname.startsWith(`${rpcPrefix}/`)) {
+      if (!options.handlers.rpc) {
+        sendJson(res, 503, { error: "Plugin still loading..." });
+        return;
+      }
+      handleOrpc(
+        req,
+        res,
+        options.handlers.rpc,
+        rpcPrefix,
+        "RPC",
+        resolveEffectContext(),
+        resolvedPort,
+      ).catch(() => {});
+      return;
+    }
+
+    if (pathname === apiPrefix || pathname.startsWith(`${apiPrefix}/`)) {
+      if (!options.handlers.api) {
+        sendJson(res, 503, { error: "Plugin still loading..." });
+        return;
+      }
+      handleOrpc(
+        req,
+        res,
+        options.handlers.api,
+        apiPrefix,
+        "OpenAPI",
+        resolveEffectContext(),
+        resolvedPort,
+      ).catch(() => {});
+      return;
+    }
+
+    if (staticHandler) {
+      staticHandler(req, res, () => {
+        sendText(res, 404, "Not Found");
+      });
+      return;
+    }
+
+    sendText(res, 404, "Not Found");
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, () => resolve());
+  });
+
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    throw new Error("Failed to resolve host port");
+  }
+  resolvedPort = address.port;
+
+  return {
+    port: resolvedPort,
+    close: async () => {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    },
+  };
+}