@moonsjs/vite 0.1.3 → 0.1.5

package/src/api.ts

@@ -0,0 +1,124 @@
+import { parse } from "@babel/parser";
+import { API_METHODS, MoonsError } from "@moonsjs/core";
+
+/**
+ * Validasi statis export modul `src/api` (PRD Addendum D.1):
+ * hanya handler method `GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS` sebagai fungsi;
+ * `default`/export lain ditolak → `E_API_HANDLER_INVALID`.
+ */
+export function assertApiModuleExports(code: string, file: string): string[] {
+  let ast: unknown;
+  try {
+    ast = parse(code, {
+      sourceType: "module",
+      plugins: file.endsWith(".tsx") ? ["typescript", "jsx"] : ["typescript"],
+    });
+  } catch {
+    return []; // biarkan bundler melaporkan syntax error
+  }
+
+  const program = (ast as { program?: { body?: Array<Record<string, unknown>> } }).program;
+  const body = program?.body ?? [];
+  const methods: string[] = [];
+
+  for (const statement of body) {
+    if (statement["type"] === "ExportDefaultDeclaration") {
+      throw apiError(
+        file,
+        "export `default` tidak didukung di modul API",
+        "Modul `src/api` hanya mengekspor handler method bernama (PRD Addendum D.1).",
+        ["Ganti menjadi `export const GET = (args) => …`", "Hapus export default"],
+      );
+    }
+    if (statement["type"] !== "ExportNamedDeclaration") {
+      continue;
+    }
+    if (statement["source"] !== undefined) {
+      // re-export `export { X } from "..."` — nama tetap dicek di bawah.
+    }
+    const declaration = statement["declaration"] as Record<string, unknown> | undefined;
+    if (declaration !== undefined) {
+      if (declaration["type"] === "VariableDeclaration") {
+        for (const declarator of (declaration["declarations"] ?? []) as Array<Record<string, unknown>>) {
+          const id = declarator["id"] as Record<string, unknown> | undefined;
+          if (id?.["type"] === "Identifier") {
+            methods.push(id["name"] as string);
+          }
+        }
+      } else if (declaration["type"] === "FunctionDeclaration") {
+        const id = declaration["id"] as Record<string, unknown> | undefined;
+        if (id?.["type"] === "Identifier") {
+          methods.push(id["name"] as string);
+        }
+      }
+      continue;
+    }
+    for (const specifier of (statement["specifiers"] ?? []) as Array<Record<string, unknown>>) {
+      const exported = specifier["exported"] as Record<string, unknown> | undefined;
+      if (exported?.["type"] === "Identifier") {
+        methods.push(exported["name"] as string);
+      }
+    }
+  }
+
+  const illegal = methods.filter((name) => !API_METHODS.includes(name as never));
+  if (illegal.length > 0) {
+    throw apiError(
+      file,
+      `export \`${illegal[0]}\` bukan handler method yang dikenal`,
+      `Handler yang legal: ${API_METHODS.join(", ")} (PRD Addendum D.1).`,
+      [
+        "Ganti nama export menjadi salah satu method HTTP",
+        "Pindahkan helper ke modul lain (mis. `src/server/…`)",
+      ],
+    );
+  }
+  if (methods.length === 0) {
+    throw apiError(
+      file,
+      "modul API tanpa handler method",
+      `Wajib ada minimal satu dari ${API_METHODS.join(", ")} (PRD Addendum D.1).`,
+      [`Tambahkan \`export const GET = (args) => new Response(…)\``],
+    );
+  }
+
+  return methods;
+}
+
+export function assertMiddlewareExports(code: string, file: string): void {
+  let ast: unknown;
+  try {
+    ast = parse(code, {
+      sourceType: "module",
+      plugins: file.endsWith(".tsx") ? ["typescript", "jsx"] : ["typescript"],
+    });
+  } catch {
+    return;
+  }
+  const program = (ast as { program?: { body?: Array<Record<string, unknown>> } }).program;
+  const hasDefault = (program?.body ?? []).some(
+    (statement) => statement["type"] === "ExportDefaultDeclaration",
+  );
+  if (!hasDefault) {
+    throw new MoonsError({
+      code: "E_MIDDLEWARE_INVALID",
+      file,
+      message: "`_middleware.ts` tanpa `export default`",
+      details: "Middleware direktori mengikuti bentuk `Middleware`: `(args) => Promise<Response>` (PRD Addendum D.3).",
+      suggestions: [
+        "Tambahkan `export default async ({ req, ctx, next }) => await next()`",
+        "Hapus file bila tidak dipakai",
+      ],
+    });
+  }
+}
+
+function apiError(file: string, message: string, details: string, suggestions: string[]): MoonsError {
+  return new MoonsError({
+    code: "E_API_HANDLER_INVALID",
+    file,
+    message,
+    details,
+    suggestions,
+  });
+}

package/src/manifest.ts

@@ -1,4 +1,4 @@
-import { findLayouts, routeKeyFromFile, type RouteDefinition } from "@moonsjs/core";
+import { findLayouts, routeKeyFromFile, type ApiRouteDefinition, type RouteDefinition } from "@moonsjs/core";
 import { relative, sep } from "node:path";
 
 export interface ClientManifestEntry {
@@ -38,10 +38,51 @@ export function buildClientManifest(
   if (errorRoute !== undefined) {
     manifest[ERROR_ROUTE_KEY] = { page: routeKeyFromFile(routesDir, errorRoute.file), layouts: [] };
   }
+  // D.3: semua boundary `_error` (termasuk bersarang) ikut manifest — payload
+  // memakai key file boundary yang dipilih runtime.
+  for (const route of routes) {
+    if (route.kind !== "error") {
+      continue;
+    }
+    const key = routeKeyFromFile(routesDir, route.file);
+    manifest[key] = { page: key, layouts: [] };
+  }
 
   return manifest;
 }
 
+/** `virtual:moons/api` (Addendum D.1 + D.3): tabel API + middleware + peta import(). */
+export function renderApiModule(
+  apiRoutes: ApiRouteDefinition[],
+  apiMiddlewares: ReadonlyArray<{ file: string; dir: string }>,
+  projectRoot: string,
+): string {
+  const loadEntries = apiRoutes
+    .map(
+      (route) =>
+        `  ${JSON.stringify(route.path)}: () => import(${JSON.stringify(rootSpecifier(projectRoot, route.file))}),`,
+    )
+    .join("\n");
+  const middlewareEntries = apiMiddlewares
+    .map(
+      (middleware) =>
+        `  ${JSON.stringify(middleware.file)}: () => import(${JSON.stringify(rootSpecifier(projectRoot, middleware.file))}),`,
+    )
+    .join("\n");
+  return [
+    "// Generated by @moons. Jangan diubah manual.",
+    `export const apiRoutes = ${JSON.stringify(apiRoutes, null, 2)};`,
+    `export const apiMiddlewares = ${JSON.stringify(apiMiddlewares, null, 2)};`,
+    "export const loadApi = {",
+    loadEntries,
+    "};",
+    "export const loadApiMiddleware = {",
+    middlewareEntries,
+    "};",
+    "",
+  ].join("\n");
+}
+
 /**
  * Isi `virtual:moons/routes`: daftar RouteDefinition, manifest client, dan
  * peta import() dinamis per file route (specifier root-relative).

package/src/payload-scan.ts

@@ -0,0 +1,53 @@
+/**
+ * Pemindaian payload SSR (nilai A1 / PRD §2): HANYA dipakai di dev sebagai
+ * peringatan — tidak ada biaya runtime di production (production tidak pernah
+ * memanggil fungsi ini; lihat `RequestHandlerOptions.payloadScan`).
+ */
+
+export interface PayloadScanOptions {
+  /** Canary `leakTest.canary` (bila dikonfigurasi). */
+  canary?: string;
+  /** Lingkungan server (biasanya `process.env`). */
+  env?: Record<string, string | undefined>;
+}
+
+export interface PayloadScanFinding {
+  kind: "canary" | "env";
+  /** Label untuk pesan: `canary` atau nama env var. */
+  label: string;
+}
+
+/**
+ * Nama env yang "mirip rahasia" — dideteksi lewat pola nama + panjang nilai
+ * minimum 12 karakter untuk menghindari false positive (keputusan pemilik).
+ */
+const SECRET_KEY_PATTERN =
+  /(SECRET|TOKEN|PASSWORD|PASSWD|PRIVATE|CREDENTIAL|AUTH|API_KEY|ACCESS_KEY|SIGNING)/i;
+
+const MIN_SECRET_LENGTH = 12;
+
+export function scanPayloadForSecrets(
+  payload: string,
+  options: PayloadScanOptions = {},
+): PayloadScanFinding[] {
+  const findings: PayloadScanFinding[] = [];
+
+  const canary = options.canary;
+  if (canary !== undefined && canary.length > 0 && payload.includes(canary)) {
+    findings.push({ kind: "canary", label: "canary" });
+  }
+
+  for (const [key, value] of Object.entries(options.env ?? {})) {
+    if (typeof value !== "string" || value.length < MIN_SECRET_LENGTH) {
+      continue;
+    }
+    if (!SECRET_KEY_PATTERN.test(key) || /PUBLIC/i.test(key)) {
+      continue;
+    }
+    if (payload.includes(value)) {
+      findings.push({ kind: "env", label: key });
+    }
+  }
+
+  return findings;
+}

package/src/plugin.ts

@@ -5,13 +5,19 @@ import {
   MoonsError,
   fnRegistryKey,
   generateTypes,
+  scanApiMiddlewares,
+  scanApiRoutes,
   scanRoutes,
   validateConfig,
+  type ApiMiddlewareDefinition,
+  type ApiRouteDefinition,
   type RouteDefinition,
 } from "@moonsjs/core";
 import { loadConfigFromFile, type Plugin, type ViteDevServer } from "vite";
+import { assertApiModuleExports, assertMiddlewareExports } from "./api";
 import { findLeak } from "./leak-check";
-import { renderRoutesModule, rootSpecifier } from "./manifest";
+import type { PackageJsonInfo } from "./server-only";
+import { renderApiModule, renderRoutesModule, rootSpecifier } from "./manifest";
 import { installDevMiddleware } from "./server/dev";
 import {
   analyzeServerFile,
@@ -49,7 +55,12 @@ export default function moons(options: MoonsVitePluginOptions = {}): Plugin {
   let isSsrBuild = false;
   let configFilePath = "";
   let routesDir = "";
-  let routes: RouteDefinition[] = [];
+  let serverOnlyPackages: ReadonlyArray<string> = [];
+  let apiDir = "";
+  let apiRoutes: ApiRouteDefinition[] = [];
+  let apiMiddlewares: ApiMiddlewareDefinition[] = [];
+  /** Cache package.json untuk gate Addendum C (dibagi lintas modul). */
+  const packageCache = new Map<string, PackageJsonInfo | null>();  let routes: RouteDefinition[] = [];
   let analysisCache = new Map<string, ServerFileAnalysis>();
   const stubTransformed = new Set<string>();
 
@@ -163,8 +174,18 @@ export default function moons(options: MoonsVitePluginOptions = {}): Plugin {
             emptyOutDir: true,
             // Entry nyata yang di-generate saat buildStart (Rolldown butuh file,
             // entry virtual tidak di-resolve lewat plugin container).
-            ssr: ".moons/server-entry.ts",
-            rollupOptions: { output: { entryFileNames: "index.js", codeSplitting: false } },
+            // D.5: dua entry — server (index) + prerender runner.
+            ssr: true,
+            rollupOptions: {
+              input: {
+                index: ".moons/server-entry.ts",
+                prerender: ".moons/prerender-entry.ts",
+              },
+              output: {
+                entryFileNames: "[name].js",
+                chunkFileNames: "chunks/[name]-[hash].js",
+              },
+            },
           },
           ssr: { noExternal: true, target: "node" as const },
         };
@@ -223,10 +244,31 @@ export default function moons(options: MoonsVitePluginOptions = {}): Plugin {
 
       const config = validateConfig(raw, { file: configFilePath, projectRoot: root });
       routesDir = resolvePath(root, config.routesDir);
+      serverOnlyPackages = config.security?.serverOnlyPackages ?? [];
+
+      // Addendum D.1: scan + validasi statis modul `src/api`.
+      apiDir = resolvePath(root, config.apiDir ?? "src/api");
+      if (existsSync(apiDir)) {
+        apiRoutes = scanApiRoutes(apiDir);
+        for (const route of apiRoutes) {
+          assertApiModuleExports(readFileSync(route.file, "utf8"), route.file);
+        }
+        apiMiddlewares = scanApiMiddlewares(apiDir);
+        for (const middleware of apiMiddlewares) {
+          assertMiddlewareExports(readFileSync(middleware.file, "utf8"), middleware.file);
+        }
+      } else {
+        apiRoutes = [];
+        apiMiddlewares = [];
+      }
     },
 
     async buildStart() {
       routes = scanRoutes(routesDir);
+      // D.3: validasi statis `_middleware.ts` pohon routes.
+      for (const middleware of routes.filter((route) => route.kind === "middleware")) {
+        assertMiddlewareExports(readFileSync(middleware.file, "utf8"), middleware.file);
+      }
       await generateTypes({
         routesDir,
         configPath: configFilePath,
@@ -239,6 +281,11 @@ export default function moons(options: MoonsVitePluginOptions = {}): Plugin {
           renderServerEntryBuild(routesDir, serverFnFileSpecifiers()),
           "utf8",
         );
+        writeFileSync(
+          resolvePath(root, ".moons/prerender-entry.ts"),
+          renderPrerenderEntry(routesDir, root, options.leakTest?.canary),
+          "utf8",
+        );
       }
     },
 
@@ -258,6 +305,8 @@ export default function moons(options: MoonsVitePluginOptions = {}): Plugin {
       switch (name) {
         case VIRTUAL_MODULES.routes:
           return renderRoutesModule(routes, routesDir, root);
+        case VIRTUAL_MODULES.api:
+          return renderApiModule(apiRoutes, apiMiddlewares, root);
         case VIRTUAL_MODULES.clientEntry:
           return '// Generated by @moons. Jangan diubah manual.\nexport { clientManifest, loadRoute } from "virtual:moons/routes";\n';
         case VIRTUAL_MODULES.config:
@@ -316,6 +365,9 @@ export default function moons(options: MoonsVitePluginOptions = {}): Plugin {
             }
           },
           analyze: (absoluteFile) => analysisCache.get(absoluteFile) ?? analyzeFile(absoluteFile),
+          apiDir,
+          serverOnlyPackages,
+          packageCache,
         });
       }
 
@@ -369,7 +421,18 @@ export default function moons(options: MoonsVitePluginOptions = {}): Plugin {
     },
 
     configureServer(server) {
-      installDevMiddleware(server, { templatePath: resolvePath(root, "index.html") });
+      installDevMiddleware(server, {
+        templatePath: resolvePath(root, "index.html"),
+        // A1: pemindaian payload SSR hanya di dev (warning), tanpa biaya di production.
+        payloadScan: {
+          ...(options.leakTest?.canary === undefined ? {} : { canary: options.leakTest.canary }),
+          env: process.env,
+        },
+        // D.1: request ke prefix API (semua method) dirutekan ke runtime.
+        ...(apiRoutes.length === 0
+          ? {}
+          : { apiPrefix: `/${apiDir.split(/[\\/]/).filter((part) => part.length > 0).pop() ?? "api"}` }),
+      });
     },
 
     async handleHotUpdate(context) {
@@ -379,12 +442,34 @@ export default function moons(options: MoonsVitePluginOptions = {}): Plugin {
         return;
       }
 
+      if (context.file.startsWith(apiDir) && existsSync(apiDir)) {
+        try {
+          apiRoutes = scanApiRoutes(apiDir);
+          for (const route of apiRoutes) {
+            assertApiModuleExports(readFileSync(route.file, "utf8"), route.file);
+          }
+          apiMiddlewares = scanApiMiddlewares(apiDir);
+          for (const middleware of apiMiddlewares) {
+            assertMiddlewareExports(readFileSync(middleware.file, "utf8"), middleware.file);
+          }
+        } catch (error) {
+          context.server.config.logger.error(String(error));
+          return;
+        }
+        invalidateVirtualModules(context.server);
+        context.server.ws.send({ type: "full-reload" });
+        return;
+      }
+
       if (!context.file.startsWith(routesDir)) {
         return;
       }
 
       try {
         routes = scanRoutes(routesDir);
+        for (const middleware of routes.filter((route) => route.kind === "middleware")) {
+          assertMiddlewareExports(readFileSync(middleware.file, "utf8"), middleware.file);
+        }
         await generateTypes({
           routesDir,
           configPath: configFilePath,
@@ -414,13 +499,16 @@ function renderConfigModule(root: string, configFilePath: string): string {
 function renderServerEntryDev(routesDir: string, eagerImports: string[]): string {
   return [
     "// Generated by @moons. Jangan diubah manual.",
-    'import { createRequestHandler } from "@moonsjs/vite/server";',
+    'import { createPluginRuntime, createRequestHandler } from "@moonsjs/vite/server";',
     'import config from "virtual:moons/config";',
     'import { routes, loadRoute } from "virtual:moons/routes";',
+    'import { apiRoutes, apiMiddlewares, loadApi, loadApiMiddleware } from "virtual:moons/api";',
     ...eagerImports.map((specifier) => `import ${JSON.stringify(specifier)};`),
     "",
-    "export function createDevHandler(shell) {",
-    `  return createRequestHandler({ routes, config, routesDir: ${JSON.stringify(routesDir)}, loadRoute, shell });`,
+    "export function createDevApp(shell, payloadScan) {",
+    "  const plugins = createPluginRuntime({ config, routes, middlewares: config.middleware ?? [] });",
+    `  const handler = createRequestHandler({ routes, apiRoutes, apiMiddlewares, loadApi, loadApiMiddleware, config, routesDir: ${JSON.stringify(routesDir)}, loadRoute, shell, onContext: (ctx) => plugins.applyExtensions(ctx), ...(payloadScan === undefined ? {} : { payloadScan }) });`,
+    "  return { handler, plugins };",
     "}",
     "",
   ].join("\n");
@@ -429,20 +517,27 @@ function renderServerEntryDev(routesDir: string, eagerImports: string[]): string
 function renderServerEntryBuild(routesDir: string, eagerImports: string[]): string {
   return [
     "// Generated by @moons. Jangan diubah manual.",
-    'import { createFileShell, createRequestHandler, startNodeServer } from "@moonsjs/vite/server";',
+    'import { createFileShell, createPluginRuntime, createRequestHandler, startNodeServer } from "@moonsjs/vite/server";',
     'import config from "virtual:moons/config";',
     'import { routes, loadRoute } from "virtual:moons/routes";',
+    'import { apiRoutes, apiMiddlewares, loadApi, loadApiMiddleware } from "virtual:moons/api";',
     ...eagerImports.map((specifier) => `import ${JSON.stringify(specifier)};`),
     "",
+    "const plugins = createPluginRuntime({ config, routes, middlewares: config.middleware ?? [] });",
     "const handler = createRequestHandler({",
     "  routes,",
+    "  apiRoutes,",
+    "  apiMiddlewares,",
+    "  loadApi,",
+    "  loadApiMiddleware,",
     "  config,",
     `  routesDir: ${JSON.stringify(routesDir)},`,
     "  loadRoute,",
     "  shell: createFileShell(),",
+    "  onContext: (ctx) => plugins.applyExtensions(ctx),",
     "});",
     "",
-    "startNodeServer(handler);",
+    "startNodeServer(handler, { plugins });",
     "",
   ].join("\n");
 }
@@ -452,6 +547,38 @@ interface ModuleGraphLike {
   invalidateModule(module: unknown): void;
 }
 
+/** Entry D.5: runner prerender (dijalankan CLI setelah build server). */
+function renderPrerenderEntry(
+  routesDir: string,
+  projectRoot: string,
+  canary: string | undefined,
+): string {
+  return [
+    "// Generated by @moons. Jangan diubah manual.",
+    'import { createFileShell, createRequestHandler, runPrerender } from "@moonsjs/vite/server";',
+    'import config from "virtual:moons/config";',
+    'import { routes, loadRoute } from "virtual:moons/routes";',
+    "",
+    "const handler = createRequestHandler({",
+    "  routes,",
+    "  config,",
+    `  routesDir: ${JSON.stringify(routesDir)},`,
+    "  loadRoute,",
+    "  shell: createFileShell(),",
+    "});",
+    "",
+    "await runPrerender({",
+    "  routes,",
+    `  routesDir: ${JSON.stringify(routesDir)},`,
+    "  loadRoute,",
+    "  handler,",
+    `  clientDir: ${JSON.stringify(resolvePath(projectRoot, "dist/client"))},`,
+    ...(canary === undefined ? [] : [`  canary: ${JSON.stringify(canary)},`]),
+    "});",
+    "",
+  ].join("\n");
+}
+
 function environmentName(context: unknown): string {
   const environment = (context as { environment?: { name?: string } } | undefined)?.environment;
   return environment?.name ?? "client";

package/src/server/dev.ts

@@ -1,43 +1,74 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { ViteDevServer } from "vite";
 import { VIRTUAL_MODULES } from "../virtual-modules";
+import type { PayloadScanOptions } from "../payload-scan";
+import type { PluginRuntime } from "./plugins";
 import type { Shell } from "./shell";
 import { createDevShell } from "./shell";
 import { sendNodeResponse, toWebRequest } from "./node";
 
+interface DevApp {
+  handler: (request: Request) => Promise<Response>;
+  plugins: PluginRuntime;
+}
+
 type DevServerEntry = {
-  createDevHandler: (shell: Shell) => (request: Request) => Promise<Response>;
+  createDevApp: (
+    shell: Shell,
+    payloadScan?: import("../payload-scan").PayloadScanOptions,
+  ) => DevApp;
 };
 
 /**
  * Middleware SSR dev: dipasang sebelum middleware internal Vite, menangani
  * request HTML dan RPC serverFn (`/_moons/fn/*`) — modul/aset tetap Vite.
+ * Handler + lifecycle plugin (Addendum B.4) diinisialisasi sekali.
  */
 export function installDevMiddleware(
   server: ViteDevServer,
-  options: { templatePath: string },
+  options: { templatePath: string; payloadScan?: PayloadScanOptions; apiPrefix?: string },
 ): void {
+  let appPromise: Promise<DevApp> | null = null;
+
+  const getApp = (): Promise<DevApp> => {
+    if (appPromise === null) {
+      appPromise = (async () => {
+        const entry = (await server.ssrLoadModule(VIRTUAL_MODULES.serverEntry)) as DevServerEntry;
+        const app = entry.createDevApp(createDevShell(server, options), options.payloadScan);
+        await app.plugins.start();
+        await app.plugins.ready();
+        return app;
+      })();
+    }
+    return appPromise;
+  };
+
+  server.httpServer?.once("close", () => {
+    void appPromise?.then((app) => app.plugins.shutdown());
+  });
+
   server.middlewares.use((req, res, next) => {
-    if (!shouldHandle(req)) {
+    if (!shouldHandle(req, options.apiPrefix)) {
       next();
       return;
     }
-    void handleRequest(server, options)(req, res).catch((error: unknown) => {
+    void handleRequest(getApp, req, res).catch((error: unknown) => {
       next(error as Error);
     });
   });
 }
 
-function handleRequest(server: ViteDevServer, options: { templatePath: string }) {
-  return async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
-    const entry = (await server.ssrLoadModule(VIRTUAL_MODULES.serverEntry)) as DevServerEntry;
-    const handler = entry.createDevHandler(createDevShell(server, options));
-    const response = await handler(await toWebRequest(req));
-    await sendNodeResponse(res, response);
-  };
+async function handleRequest(
+  getApp: () => Promise<DevApp>,
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<void> {
+  const app = await getApp();
+  const response = await app.handler(await toWebRequest(req));
+  await sendNodeResponse(res, response);
 }
 
-function shouldHandle(req: IncomingMessage): boolean {
+function shouldHandle(req: IncomingMessage, apiPrefix: string | undefined): boolean {
   const path = new URL(req.url ?? "/", "http://localhost").pathname;
 
   // RPC serverFn (semua method): dulu hanya GET/HEAD HTML yang dirutekan,
@@ -47,6 +78,11 @@ function shouldHandle(req: IncomingMessage): boolean {
     return true;
   }
 
+  // Addendum D.1: endpoint `src/api` (semua method) dirutekan ke runtime.
+  if (apiPrefix !== undefined && (path === apiPrefix || path.startsWith(`${apiPrefix}/`))) {
+    return true;
+  }
+
   if (req.method !== "GET" && req.method !== "HEAD") {
     return false;
   }