@unieojs/unio-evjs-adapter 0.1.0

package/src/emit.ts

@@ -0,0 +1,384 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+import type {
+  AdapterBuildResult,
+  CapabilityStatus,
+  ClientManifest,
+  EmitUboaOptions,
+  PageManifestEntry,
+  ServerManifest,
+  UboaArtifact,
+  UboaCapabilities,
+  UboaMiddleware,
+  UboaRoute,
+  UboaServerFunctionDescriptor,
+} from "./types.js";
+import {
+  assertClientManifest,
+  assertServerManifest,
+} from "./manifest.js";
+import {
+  isRecord,
+  normalizeRoutePath,
+  pathExists,
+  routeId,
+  toPosix,
+  writeJson,
+} from "./utils.js";
+
+const ADAPTER_PACKAGE = "@unieojs/unio-evjs-adapter";
+const UBOA_VERSION = "1.0.0";
+const DEFAULT_SERVER_FUNCTION = "evjs";
+const DEFAULT_SERVER_ENDPOINT = "/api/fn";
+
+interface ResolvedManifests {
+  clientManifest: ClientManifest;
+  serverManifest?: ServerManifest;
+  clientRoot: string;
+  serverRoot: string;
+}
+
+type ServerManifestWithEntry = ServerManifest & { entry: string };
+
+function outputRoot(cwd: string, outputDir?: string): string {
+  return path.resolve(cwd, outputDir ?? ".unio/output");
+}
+
+async function resolveBuildInputs(
+  options: EmitUboaOptions,
+): Promise<ResolvedManifests> {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const clientManifest = options.clientManifest;
+  const serverManifest = options.serverManifest;
+
+  if (!clientManifest) {
+    throw new Error(
+      "EVJS client manifest must be provided from @evjs/ev buildEnd metadata.",
+    );
+  }
+  assertClientManifest(clientManifest);
+  if (serverManifest) {
+    assertServerManifest(serverManifest);
+  }
+
+  return {
+    clientManifest,
+    serverManifest,
+    clientRoot: await resolveClientRoot(cwd, clientManifest, serverManifest),
+    serverRoot: path.join(cwd, "dist/server"),
+  };
+}
+
+async function resolveClientRoot(
+  cwd: string,
+  clientManifest: ClientManifest,
+  serverManifest: ServerManifest | undefined,
+): Promise<string> {
+  const fullstackClientRoot = path.join(cwd, "dist/client");
+  const flatClientRoot = path.join(cwd, "dist");
+
+  if (
+    serverManifest ||
+    (
+      clientManifest.pages &&
+      Object.keys(clientManifest.pages).length > 0
+    )
+  ) {
+    return fullstackClientRoot;
+  }
+
+  if (await pathExists(path.join(flatClientRoot, "index.html"))) {
+    return flatClientRoot;
+  }
+
+  return await pathExists(fullstackClientRoot)
+    ? fullstackClientRoot
+    : flatClientRoot;
+}
+
+async function copyIfExists(source: string, dest: string): Promise<boolean> {
+  if (!(await pathExists(source))) return false;
+  await fs.mkdir(path.dirname(dest), { recursive: true });
+  await fs.cp(source, dest, { recursive: true });
+  return true;
+}
+
+function buildContentVersion(): string {
+  const parts = [
+    process.env.SPRINT_ID ? `SPRINT=${process.env.SPRINT_ID}` : undefined,
+    process.env.COMMIT_ID ? `COMMIT=${process.env.COMMIT_ID}` : undefined,
+  ].filter(Boolean);
+
+  return parts.length > 0 ? parts.join(", ") : "local";
+}
+
+function hasServerEntry(
+  manifest: ServerManifest | undefined,
+): manifest is ServerManifestWithEntry {
+  return Boolean(manifest?.entry);
+}
+
+function hasRscMetadata(manifest: ServerManifest | undefined): boolean {
+  if (!isRecord(manifest) || !isRecord(manifest.rsc)) return false;
+  return Object.keys(manifest.rsc).length > 0;
+}
+
+function buildCapabilities(
+  clientManifest: ClientManifest,
+  serverManifest: ServerManifest | undefined,
+): UboaCapabilities {
+  const serverEnabled = hasServerEntry(serverManifest);
+  const hasFns = serverEnabled && Object.keys(serverManifest.fns).length > 0;
+
+  let serverFunctionIntrospection: CapabilityStatus = "unsupported";
+  if (serverEnabled) {
+    serverFunctionIntrospection = hasFns ? "supported" : "degraded";
+  }
+
+  const rsc: CapabilityStatus = hasRscMetadata(serverManifest)
+    ? "partial"
+    : "unsupported";
+
+  return {
+    static: clientManifest ? "supported" : "unsupported",
+    routes: "supported",
+    serverlessFunction: serverEnabled ? "supported" : "unsupported",
+    serverFunctionIntrospection,
+    restRouteIntrospection: serverEnabled ? "degraded" : "unsupported",
+    edgeMiddleware: "unsupported",
+    rsc,
+    imageOptimization: "unsupported",
+  };
+}
+
+function staticRoutesForRoutes(
+  routes: Array<{ path: string }> | undefined,
+  entry: string,
+): UboaRoute[] {
+  const sourceRoutes =
+    routes && routes.length > 0 ? routes : [{ path: "/" }, { path: "*" }];
+  const seen = new Set<string>();
+  const result: UboaRoute[] = [];
+
+  for (const route of sourceRoutes) {
+    const match = normalizeRoutePath(route.path);
+    const key = `${match}:${entry}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push({
+      id: routeId("static", match),
+      match,
+      type: "static",
+      entry,
+    });
+  }
+
+  return result;
+}
+
+function pageEntry(pageName: string): string {
+  return `static/${pageName}.html`;
+}
+
+function pageRoutes(
+  pages: Record<string, PageManifestEntry>,
+): UboaRoute[] {
+  const routes: UboaRoute[] = [];
+
+  for (const pageName of Object.keys(pages)) {
+    const match = pageName === "index" ? "/" : normalizeRoutePath(pageName);
+    routes.push({
+      id: routeId("static", match),
+      match,
+      type: "static",
+      entry: pageEntry(pageName),
+    });
+  }
+
+  return routes;
+}
+
+function buildStaticRoutes(clientManifest: ClientManifest): UboaRoute[] {
+  if (clientManifest.pages && Object.keys(clientManifest.pages).length > 0) {
+    return pageRoutes(clientManifest.pages);
+  }
+
+  return staticRoutesForRoutes(clientManifest.routes, "static/index.html");
+}
+
+function serverRoutes(serverFunctionName: string, endpoint: string): UboaRoute[] {
+  return [
+    {
+      id: "server-evjs-rpc",
+      match: endpoint,
+      type: "serverFunction",
+      serverFunction: serverFunctionName,
+      methods: ["POST"],
+    },
+    {
+      id: "server-evjs-api-fallback",
+      match: "/api/:path*",
+      type: "serverFunction",
+      serverFunction: serverFunctionName,
+    },
+  ];
+}
+
+async function emitServerFunction(
+  root: string,
+  serverRoot: string,
+  serverManifest: ServerManifestWithEntry,
+  serverFunctionName: string,
+  endpoint: string,
+  extendDescriptor: EmitUboaOptions["extendServerFunctionDescriptor"],
+): Promise<void> {
+  const functionDir = path.join(root, "server-functions", serverFunctionName);
+  const sourceEntry = path.join(serverRoot, serverManifest.entry);
+
+  if (!(await pathExists(sourceEntry))) {
+    throw new Error(`EVJS server entry not found: ${toPosix(sourceEntry)}`);
+  }
+
+  await fs.mkdir(path.dirname(functionDir), { recursive: true });
+  await fs.cp(serverRoot, functionDir, { recursive: true });
+
+  const descriptor: UboaServerFunctionDescriptor = {
+    name: serverFunctionName,
+    runtime: "nodejs22",
+    entry: toPosix(serverManifest.entry),
+    handler: "default",
+    handlerProtocol: "fetch",
+    memory: 512,
+    maxDuration: 10,
+    environment: {},
+    bindings: {},
+    framework: {
+      name: "evjs",
+      serverFunctionEndpoint: endpoint,
+      serverManifest: "dist/server/manifest.json",
+      serverFunctions: Object.keys(serverManifest.fns),
+    },
+    source: {
+      entry: `dist/server/${serverManifest.entry}`,
+    },
+  };
+  const extendedDescriptor = extendDescriptor
+    ? await extendDescriptor({ descriptor, serverFunctionName })
+    : descriptor;
+
+  if (!isRecord(extendedDescriptor)) {
+    throw new Error("extendServerFunctionDescriptor must return an object.");
+  }
+
+  await writeJson(
+    path.join(functionDir, "serverFunction.json"),
+    extendedDescriptor,
+  );
+}
+
+export async function emitUboa(
+  options: EmitUboaOptions,
+): Promise<AdapterBuildResult> {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const root = outputRoot(cwd, options.outputDir);
+  const serverFunctionName = options.serverFunctionName ?? DEFAULT_SERVER_FUNCTION;
+  const serverEndpoint =
+    options.serverFunctionEndpoint ?? DEFAULT_SERVER_ENDPOINT;
+  const { clientManifest, serverManifest, clientRoot, serverRoot } =
+    await resolveBuildInputs({ ...options, cwd });
+  const warnings: string[] = [];
+
+  await fs.rm(root, { recursive: true, force: true });
+  await fs.mkdir(root, { recursive: true });
+
+  await copyIfExists(clientRoot, path.join(root, "static"));
+
+  const routes = buildStaticRoutes(clientManifest);
+  const middleware: UboaMiddleware[] = [];
+  let artifacts: UboaArtifact[] = [
+    { id: "static", resourceKind: "assets", path: "static" },
+  ];
+
+  if (hasServerEntry(serverManifest)) {
+    await emitServerFunction(
+      root,
+      serverRoot,
+      serverManifest,
+      serverFunctionName,
+      serverEndpoint,
+      options.extendServerFunctionDescriptor,
+    );
+    routes.push(...serverRoutes(serverFunctionName, serverEndpoint));
+    artifacts.push({
+      id: serverFunctionName,
+      resourceKind: "serverFunction",
+      path: `server-functions/${serverFunctionName}`,
+    });
+
+    if (Object.keys(serverManifest.fns).length === 0) {
+      warnings.push(
+        "EVJS serverManifest.fns is empty; server function introspection is degraded.",
+      );
+    }
+  }
+
+  if (options.extendArtifacts) {
+    const extendedArtifacts = await options.extendArtifacts({
+      artifacts,
+      serverFunctionName,
+    });
+
+    if (!Array.isArray(extendedArtifacts)) {
+      throw new Error("extendArtifacts must return an array.");
+    }
+
+    artifacts = extendedArtifacts;
+  }
+
+  const capabilities = buildCapabilities(clientManifest, serverManifest);
+
+  await writeJson(path.join(root, "unio.json"), {
+    version: UBOA_VERSION,
+    framework: {
+      name: "evjs",
+      version: "unknown",
+      adapter: ADAPTER_PACKAGE,
+    },
+    build: {
+      contentVersion: buildContentVersion(),
+      buildId: process.env.BUILD_ID || process.env.TASK_ID || "local",
+    },
+    capabilities,
+    warnings,
+  });
+  await writeJson(path.join(root, "routes.json"), routes);
+  await writeJson(path.join(root, "middleware.json"), middleware);
+  await writeJson(path.join(root, "artifacts.json"), { artifacts });
+  await writeJson(path.join(root, "features.json"), {
+    features: [],
+    evjs: {
+      serverFunctions: serverManifest ? Object.keys(serverManifest.fns) : [],
+      routeHandlers: hasServerEntry(serverManifest) ? "degraded" : "unsupported",
+    },
+  });
+  await writeJson(path.join(root, "observability.json"), {
+    adapter: ADAPTER_PACKAGE,
+    framework: "evjs",
+    buildId: process.env.BUILD_ID || process.env.TASK_ID || "local",
+  });
+
+  await options.afterEmit?.({
+    outputDir: root,
+    serverFunctionName,
+  });
+
+  return {
+    outputDir: root,
+    routes,
+    middleware,
+    artifacts,
+    capabilities,
+    warnings,
+  };
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+export { build } from "./build.js";
+export { detect } from "./detect.js";
+export { emitUboa } from "./emit.js";
+export { unio } from "./plugin.js";
+export { validate } from "./validate.js";
+export type {
+  AdapterBuildResult,
+  AfterEmitContext,
+  BuildOptions,
+  CapabilityStatus,
+  ClientManifest,
+  DetectResult,
+  EmitUboaOptions,
+  EvBuildResult,
+  EvPlugin,
+  EvPluginContext,
+  EvPluginHooks,
+  ExtendArtifactsContext,
+  ExtendServerFunctionDescriptorContext,
+  PageManifestEntry,
+  RouteEntry,
+  ServerFnEntry,
+  ServerManifest,
+  UboaApiSchemaArtifact,
+  UboaApiSchemaFormat,
+  UboaArtifact,
+  UboaArtifactReference,
+  UboaArtifactResourceKind,
+  UboaAssetsArtifact,
+  UboaCapabilities,
+  UboaEdgeBundleArtifact,
+  UboaEdgeFunctionRoute,
+  UboaEdgeMiddleware,
+  UboaMiddleware,
+  UboaRoute,
+  UboaServerFunctionDescriptor,
+  UboaServerFunctionArtifact,
+  UboaServerFunctionRoute,
+  UboaServerlessMiddleware,
+  UboaStaticRoute,
+  UnioEvjsAdapterOptions,
+  ValidationResult,
+} from "./types.js";
+
+export { unio as default } from "./plugin.js";

package/src/manifest.ts

@@ -0,0 +1,108 @@
+import type {
+  ClientManifest,
+  PageManifestEntry,
+  RouteEntry,
+  ServerFnEntry,
+  ServerManifest,
+} from "./types.js";
+
+import { isRecord, isStringArray } from "./utils.js";
+
+function invalidManifest(kind: "client" | "server", reason: string): Error {
+  return new Error(`Invalid EVJS ${kind} manifest: ${reason}`);
+}
+
+function assertRouteEntry(value: unknown, label: string): asserts value is RouteEntry {
+  if (!isRecord(value) || typeof value.path !== "string") {
+    throw invalidManifest("client", `${label}.path must be a string`);
+  }
+}
+
+function assertRoutes(value: unknown, label: string): asserts value is RouteEntry[] {
+  if (!Array.isArray(value)) {
+    throw invalidManifest("client", `${label} must be an array`);
+  }
+
+  value.forEach((route, index) => {
+    assertRouteEntry(route, `${label}[${index}]`);
+  });
+}
+
+function assertPageManifestEntry(
+  value: unknown,
+  label: string,
+): asserts value is PageManifestEntry {
+  if (!isRecord(value)) {
+    throw invalidManifest("client", `${label} must be an object`);
+  }
+  assertAssets(value.assets, `${label}.assets`);
+  if (value.routes !== undefined) {
+    assertRoutes(value.routes, `${label}.routes`);
+  }
+}
+
+function assertAssets(
+  value: unknown,
+  label: string,
+): asserts value is { js: string[]; css: string[] } {
+  if (!isRecord(value)) {
+    throw invalidManifest("client", `${label} must be an object`);
+  }
+  if (!isStringArray(value.js)) {
+    throw invalidManifest("client", `${label}.js must be an array`);
+  }
+  if (!isStringArray(value.css)) {
+    throw invalidManifest("client", `${label}.css must be an array`);
+  }
+}
+
+export function assertClientManifest(value: unknown): asserts value is ClientManifest {
+  if (!isRecord(value)) {
+    throw invalidManifest("client", "manifest must be an object");
+  }
+  if (value.version !== 1) {
+    throw invalidManifest("client", "version must be 1");
+  }
+
+  assertAssets(value.assets, "assets");
+
+  if (value.routes !== undefined) {
+    assertRoutes(value.routes, "routes");
+  }
+
+  if (value.pages !== undefined) {
+    if (!isRecord(value.pages)) {
+      throw invalidManifest("client", "pages must be an object");
+    }
+    for (const [pageName, page] of Object.entries(value.pages)) {
+      assertPageManifestEntry(page, `pages.${pageName}`);
+    }
+  }
+}
+
+function assertServerFnEntry(
+  value: unknown,
+  label: string,
+): asserts value is ServerFnEntry {
+  if (!isRecord(value)) {
+    throw invalidManifest("server", `${label} must be an object`);
+  }
+}
+
+export function assertServerManifest(value: unknown): asserts value is ServerManifest {
+  if (!isRecord(value)) {
+    throw invalidManifest("server", "manifest must be an object");
+  }
+  if (value.version !== 1) {
+    throw invalidManifest("server", "version must be 1");
+  }
+  if (value.entry !== undefined && typeof value.entry !== "string") {
+    throw invalidManifest("server", "entry must be a string when present");
+  }
+  if (!isRecord(value.fns)) {
+    throw invalidManifest("server", "fns must be an object");
+  }
+  for (const [fnId, fnEntry] of Object.entries(value.fns)) {
+    assertServerFnEntry(fnEntry, `fns.${fnId}`);
+  }
+}

package/src/plugin.ts

@@ -0,0 +1,39 @@
+import type {
+  AdapterBuildResult,
+  EvPlugin,
+  UnioEvjsAdapterOptions,
+} from "./types.js";
+import { emitUboa } from "./emit.js";
+
+export const UNIO_PLUGIN_NAME = "@unieojs/unio-evjs-adapter";
+
+export function createUnioPlugin(
+  options: UnioEvjsAdapterOptions = {},
+  onResult?: (result: AdapterBuildResult) => void,
+): EvPlugin {
+  return {
+    name: UNIO_PLUGIN_NAME,
+    setup(ctx) {
+      const cwd = options.cwd ?? ctx.cwd;
+      const isProductionBuild = ctx.mode === "production";
+
+      return {
+        async buildEnd(result) {
+          if (!isProductionBuild) return;
+
+          const adapterResult = await emitUboa({
+            ...options,
+            cwd,
+            clientManifest: result.clientManifest,
+            serverManifest: result.serverManifest,
+          });
+          onResult?.(adapterResult);
+        },
+      };
+    },
+  };
+}
+
+export function unio(options: UnioEvjsAdapterOptions = {}): EvPlugin {
+  return createUnioPlugin(options);
+}