@moonsjs/vite 0.1.5 → 0.1.7

package/src/server/handler.ts

@@ -151,7 +151,7 @@ export function createRequestHandler(
           code: "E_API_HANDLER_INVALID",
           file: route.file,
           message: "modul API tidak mengekspor objek handler",
-          details: `Modul \`${route.path}\` harus mengekspor handler method (PRD Addendum D.1).`,
+          details: `Modul \`${route.path}\` harus mengekspor handler method.`,
           suggestions: ["Export `GET`/`POST`/… sebagai fungsi `(args) => Response`"],
         }),
         route,
@@ -194,7 +194,7 @@ export function createRequestHandler(
             code: "E_API_HANDLER_INVALID",
             file: route.file,
             message: `handler \`${requestMethod}\` tidak mengembalikan \`Response\``,
-            details: "Handler API wajib mengembalikan `new Response(...)` (PRD Addendum D.1).",
+            details: "Handler API wajib mengembalikan `new Response(...)`.",
             suggestions: ["Kembalikan `new Response(body, { status, headers })`"],
           }),
           route,
@@ -303,7 +303,7 @@ export function createRequestHandler(
           code: "E_MIDDLEWARE_INVALID",
           file: definition.file,
           message: "`_middleware.ts` tidak meng-export default fungsi",
-          details: "Middleware direktori mengikuti bentuk `(args) => Promise<Response>` (Addendum D.3).",
+          details: "Middleware direktori mengikuti bentuk `(args) => Promise<Response>`.",
           suggestions: ["Export default `async ({ req, ctx, next }) => await next()`"],
         });
       }
@@ -334,7 +334,7 @@ export function createRequestHandler(
           code: "E_MIDDLEWARE_INVALID",
           file: definition.file,
           message: "`_middleware.ts` tidak meng-export default fungsi",
-          details: "Middleware direktori mengikuti bentuk `(args) => Promise<Response>` (Addendum D.3).",
+          details: "Middleware direktori mengikuti bentuk `(args) => Promise<Response>`.",
           suggestions: ["Export default `async ({ req, ctx, next }) => await next()`"],
         });
       }
@@ -497,7 +497,7 @@ async function runRouteMeta(
       code: "E_INTERNAL",
       file,
       message: "export `meta` harus berupa fungsi `({ data }) => RouteMeta`",
-      details: "Bentuk `meta` mengikuti PRD §11.2 (Addendum B.1).",
+      details: "Bentuk `meta` mengikuti ",
       suggestions: [
         "Ubah menjadi `export const meta = ({ data }) => ({ title: \"...\" })`",
         "Atau hapus export `meta`",
@@ -510,7 +510,7 @@ async function runRouteMeta(
       code: "E_INTERNAL",
       file,
       message: "`meta()` harus mengembalikan objek RouteMeta",
-      details: "Nilai yang dikembalikan dipakai untuk <title>/description/og (Addendum B.1).",
+      details: "Nilai yang dikembalikan dipakai untuk <title>/description/og.",
       suggestions: ["Kembalikan objek, mis. `({ title: \"Halaman\" })`"],
     });
   }
@@ -602,7 +602,7 @@ function warnPayloadFindings(
     }
     warned.add(label);
     console.warn(
-      `[moons] peringatan dev: payload SSR memuat ${label} — jangan mengembalikan rahasia dari loader (PRD §2/§16.6).`,
+      `[moons] peringatan dev: payload SSR memuat ${label} — jangan mengembalikan rahasia dari loader.`,
     );
   }
 }

package/src/server/isr.ts

@@ -0,0 +1,81 @@
+import { renameSync, writeFileSync } from "node:fs";
+import { scanPayloadForSecrets } from "../payload-scan";
+
+/**
+ * ISR / revalidate on-demand (PRD Addendum E.1): file prerender yang kedaluwarsa
+ * disajikan apa adanya (stale-while-revalidate) sambil diregenerasi via handler
+ * SSR in-process. Tulis atomik + guard kebocoran fail-closed.
+ */
+export function shouldRevalidate(input: {
+  mtimeMs: number;
+  revalidateSeconds: number;
+  now?: number;
+}): boolean {
+  const now = input.now ?? Date.now();
+  return now - input.mtimeMs >= input.revalidateSeconds * 1000;
+}
+
+export interface RevalidateOptions {
+  /** Path URL ternormalisasi (mis. "/blog/hello"). */
+  pathname: string;
+  /** File HTML yang akan ditimpa. */
+  file: string;
+  handler: (request: Request) => Promise<Response>;
+  canary?: string;
+  env?: Record<string, string | undefined>;
+  log?: (message: string) => void;
+}
+
+const inflight = new Map<string, Promise<void>>();
+
+/** Regenerasi ter-dedupe per path (panggilan paralel berbagi promise). */
+export function revalidatePrerendered(options: RevalidateOptions): Promise<void> {
+  const existing = inflight.get(options.pathname);
+  if (existing !== undefined) {
+    return existing;
+  }
+  const task = runRevalidate(options).finally(() => {
+    inflight.delete(options.pathname);
+  });
+  inflight.set(options.pathname, task);
+  return task;
+}
+
+async function runRevalidate(options: RevalidateOptions): Promise<void> {
+  const log = options.log ?? ((message: string) => console.log(message));
+  try {
+    const response = await options.handler(
+      new Request(`http://localhost${options.pathname}`, {
+        method: "GET",
+        headers: { "x-moons-prerender": "1" },
+      }),
+    );
+    if (response.status !== 200) {
+      log(`[moons] isr: lewati ${options.pathname} (status ${response.status})`);
+      return;
+    }
+    const html = await response.text();
+    const findings = scanPayloadForSecrets(html, {
+      ...(options.canary === undefined ? {} : { canary: options.canary }),
+      env: options.env ?? process.env,
+    });
+    if (findings.length > 0) {
+      const labels = findings
+        .map((finding) => (finding.kind === "canary" ? "canary" : `env(${finding.label})`))
+        .join(", ");
+      // Fail-closed: jangan menimpa file statis dengan konten bocor.
+      log(`[moons] isr: TIDAK menulis ${options.pathname} — memuat ${labels}`);
+      return;
+    }
+    const tmp = `${options.file}.tmp-${process.pid}`;
+    writeFileSync(tmp, html);
+    renameSync(tmp, options.file);
+  } catch (error) {
+    log(`[moons] isr: gagal regenerasi ${options.pathname}: ${String(error)}`);
+  }
+}
+
+/** Test helper: bersihkan dedupe in-flight. */
+export function __resetIsrInflight(): void {
+  inflight.clear();
+}

package/src/server/node-server.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { createServer, type Server } from "node:http";
 import { extname, join, resolve, sep } from "node:path";
+import { revalidatePrerendered, shouldRevalidate } from "./isr";
 import { sendNodeResponse, toWebRequest } from "./node";
 import type { PluginRuntime } from "./plugins";
 import { installGracefulShutdown } from "./shutdown";
@@ -36,6 +37,8 @@ export interface NodeServerOptions {
   shutdownTimeoutMs?: number;
   /** Lifecycle plugin (Addendum B.4) — onStart/onReady/onShutdown. */
   plugins?: PluginRuntime;
+  /** Canary `leakTest.canary` untuk guard ISR (Addendum E.1). */
+  canary?: string;
 }
 
 /**
@@ -57,6 +60,7 @@ export function startNodeServer(
         if (req.method === "GET" || req.method === "HEAD") {
           const staticFile = resolveStaticFile(clientDir, url.pathname);
           if (staticFile !== null) {
+            scheduleRevalidation(staticFile, url.pathname, handler, options, clientDir);
             const body = readFileSync(staticFile);
             res.statusCode = 200;
             res.setHeader("content-type", MIME_TYPES[extname(staticFile).toLowerCase()] ?? "application/octet-stream");
@@ -125,7 +129,7 @@ export function resolveStaticFile(clientDir: string, pathname: string): string |
   //    statis — bukan shell `index.html` biasa (yang berarti bypass SSR).
   const normalized = decoded.length > 1 ? decoded.replace(/\/+$/, "") : decoded;
   const manifest = readPrerenderManifest(clientDir);
-  if (manifest.has(normalized)) {
+  if (manifest.paths.has(normalized)) {
     const target = normalized === "/" ? "index.html" : `${normalized.slice(1)}/index.html`;
     const candidate = safeWithin(clientDir, `./${target}`);
     if (candidate !== null && isFile(candidate)) {
@@ -148,22 +152,91 @@ function isFile(path: string): boolean {
   return existsSync(path) && statSync(path).isFile();
 }
 
-let prerenderManifestCache: { file: string; mtimeMs: number; paths: Set<string> } | null = null;
+export interface PrerenderManifestInfo {
+  paths: Set<string>;
+  revalidate: Map<string, number>;
+}
+
+let prerenderManifestCache:
+  | { file: string; mtimeMs: number; info: PrerenderManifestInfo }
+  | null = null;
 
-function readPrerenderManifest(clientDir: string): Set<string> {
+function readPrerenderManifest(clientDir: string): PrerenderManifestInfo {
   const file = join(clientDir, "_moons_prerender.json");
+  const empty: PrerenderManifestInfo = { paths: new Set(), revalidate: new Map() };
   try {
     const mtimeMs = statSync(file).mtimeMs;
-    if (prerenderManifestCache !== null && prerenderManifestCache.file === file && prerenderManifestCache.mtimeMs === mtimeMs) {
-      return prerenderManifestCache.paths;
+    if (
+      prerenderManifestCache !== null &&
+      prerenderManifestCache.file === file &&
+      prerenderManifestCache.mtimeMs === mtimeMs
+    ) {
+      return prerenderManifestCache.info;
+    }
+    const json = JSON.parse(readFileSync(file, "utf8")) as {
+      paths?: unknown;
+      version?: unknown;
+      entries?: unknown;
+    };
+    const paths = new Set<string>();
+    const revalidate = new Map<string, number>();
+    if (Array.isArray(json.paths)) {
+      // Manifest v1 (D.5) — tanpa revalidate.
+      for (const path of json.paths) {
+        if (typeof path === "string") {
+          paths.add(path);
+        }
+      }
     }
-    const json = JSON.parse(readFileSync(file, "utf8")) as { paths?: unknown };
-    const paths = new Set(
-      Array.isArray(json.paths) ? json.paths.filter((path): path is string => typeof path === "string") : [],
-    );
-    prerenderManifestCache = { file, mtimeMs, paths };
-    return paths;
+    if (Array.isArray(json.entries)) {
+      // Manifest v2 (E.1).
+      for (const entry of json.entries as Array<Record<string, unknown>>) {
+        if (entry === null || typeof entry !== "object" || typeof entry["path"] !== "string") {
+          continue;
+        }
+        const path = entry["path"] as string;
+        paths.add(path);
+        const seconds = entry["revalidate"];
+        if (typeof seconds === "number" && Number.isFinite(seconds) && seconds >= 0) {
+          revalidate.set(path, seconds);
+        }
+      }
+    }
+    const info = { paths, revalidate };
+    prerenderManifestCache = { file, mtimeMs, info };
+    return info;
   } catch {
-    return new Set();
+    return empty;
   }
 }
+
+/** ISR: jika file prerender kedaluwarsa, regenerasi background (SWR). */
+function scheduleRevalidation(
+  staticFile: string,
+  pathname: string,
+  handler: (request: Request) => Promise<Response>,
+  options: NodeServerOptions,
+  clientDir: string,
+): void {
+  const normalized = pathname.length > 1 ? pathname.replace(/\/+$/, "") : pathname;
+  const seconds = readPrerenderManifest(clientDir).revalidate.get(normalized);
+  if (seconds === undefined || seconds < 0) {
+    return;
+  }
+  let mtimeMs: number;
+  try {
+    mtimeMs = statSync(staticFile).mtimeMs;
+  } catch {
+    return;
+  }
+  if (!shouldRevalidate({ mtimeMs, revalidateSeconds: seconds })) {
+    return;
+  }
+  void revalidatePrerendered({
+    pathname: normalized,
+    file: staticFile,
+    handler,
+    ...(options.canary === undefined ? {} : { canary: options.canary }),
+  });
+}
+

package/src/server/prerender.ts

@@ -36,7 +36,7 @@ export async function runPrerender(options: PrerenderOptions): Promise<Prerender
   const env = options.env ?? process.env;
   let written = 0;
   let skipped = 0;
-  const writtenPaths: string[] = [];
+  const entries: Array<{ path: string; revalidate?: number }> = [];
 
   const pages = options.routes.filter((route) => route.kind === "page");
   for (const route of pages) {
@@ -47,6 +47,28 @@ export async function runPrerender(options: PrerenderOptions): Promise<Prerender
     }
     const module = (await load()) as RouteModule;
     const prerender = module.prerender;
+    const revalidate = module.revalidate;
+
+    // Addendum E.1: `revalidate` hanya sah bersama `prerender`.
+    if (revalidate !== undefined) {
+      if (
+        typeof revalidate !== "number" ||
+        !Number.isFinite(revalidate) ||
+        revalidate < 0 ||
+        prerender !== true
+      ) {
+        throw new MoonsError({
+          code: "E_ISR_INVALID",
+          file: route.file,
+          message: "`revalidate` tidak valid atau dipakai tanpa `prerender = true`",
+          details: "ISR berbasis file: `revalidate` (detik, number >= 0) + `prerender`.",
+          suggestions: [
+            "Gunakan angka detik, mis. `export const revalidate = 60`",
+            "Tambahkan `export const prerender = true` pada page yang sama",
+          ],
+        });
+      }
+    }
 
     if (prerender !== true) {
       if (prerender !== undefined && prerender !== false) {
@@ -90,7 +112,7 @@ export async function runPrerender(options: PrerenderOptions): Promise<Prerender
           file: route.file,
           message: `hasil prerender \`${pathname}\` memuat ${labels}`,
           details:
-            "HTML statis permanen — rahasia yang ter-prerender tidak bisa ditarik kembali (PRD Addendum D.5).",
+            "HTML statis permanen — rahasia yang ter-prerender tidak bisa ditarik kembali.",
           suggestions: [
             "Jangan mengembalikan nilai env rahasia dari loader yang di-prerender",
             "Matikan `prerender` untuk route ini atau pindahkan datanya ke serverFn request-time",
@@ -101,15 +123,19 @@ export async function runPrerender(options: PrerenderOptions): Promise<Prerender
       const file = outputFile(options.clientDir, pathname);
       mkdirSync(dirname(file), { recursive: true });
       writeFileSync(file, html);
-      writtenPaths.push(pathname);
+      entries.push(
+        typeof revalidate === "number" && revalidate >= 0
+          ? { path: pathname, revalidate }
+          : { path: pathname },
+      );
       written += 1;
     }
   }
 
-  // Manifest agar static server tahu path mana yang boleh dilayani statis.
+  // Manifest v2 (Addendum E.1): entries + revalidate; reader tetap menerima v1.
   writeFileSync(
     join(options.clientDir, PRERENDER_MANIFEST_FILE),
-    `${JSON.stringify({ paths: writtenPaths }, null, 2)}\n`,
+    `${JSON.stringify({ version: 2, entries }, null, 2)}\n`,
   );
 
   log(`[moons] prerender selesai: ${written} file (${skipped} dilewati)`);
@@ -132,7 +158,7 @@ async function resolvePathnames(route: RouteDefinition, module: RouteModule): Pr
       code: "E_PRERENDER_NO_PATHS",
       file: route.file,
       message: "route dynamic ber-`prerender = true` tanpa `export const paths`",
-      details: "Prerender butuh daftar param untuk merender tiap path (PRD Addendum D.5).",
+      details: "Prerender butuh daftar param untuk merender tiap path.",
       suggestions: [
         'Tambahkan `export const paths = () => [{ id: "…" }]`',
         "Atau hapus `prerender` agar dirender SSR saat request",
@@ -221,7 +247,7 @@ function prerenderError(route: RouteDefinition, message: string): MoonsError {
     code: "E_PRERENDER_INVALID",
     file: route.file,
     message,
-    details: "Kontrak prerender mengikuti PRD Addendum D.5.",
+    details: "Kontrak prerender mengikuti.",
     suggestions: [
       "Perbaiki bentuk `paths`/param agar cocok dengan pola route",
       "Jangan memakai `redirect()` pada route yang di-prerender",

package/src/server/shell.ts

@@ -120,7 +120,7 @@ export function createFileShell(options: { clientDir?: string } = {}): Shell {
           code: "E_INTERNAL",
           file,
           message: "`dist/client/index.html` tidak ditemukan",
-          details: "Build client harus dijalankan sebelum server produksi dinyalakan (PRD §18).",
+          details: "Build client harus dijalankan sebelum server produksi dinyalakan.",
           suggestions: ["Jalankan `bun run build` lebih dulu"],
         });
       }

package/src/server-only.ts

@@ -211,7 +211,7 @@ export function serverOnlyImportError(input: {
     file: input.relativeFile,
     line: input.line,
     message: `mengimpor${input.dynamic === true ? " (dynamic)" : ""} \`${input.specifier}\` — paket server-only \`${input.packageName}\``,
-    details: `${sourceLabel}\nPaket server-only tidak boleh masuk bundle client (PRD Addendum C).`,
+    details: `${sourceLabel}\nPaket server-only tidak boleh masuk bundle client.`,
     suggestions: [
       "Pindahkan operasi tersebut ke `*.server.ts` dan panggil lewat serverFn",
       "Atau ganti/hapus import tersebut di modul client",

package/src/transform.ts

@@ -542,7 +542,7 @@ export function renderServerFnStub(
           annotation: fn.name,
           message: `schema ${kind} serverFn \`${fn.name}\` merujuk deklarasi lokal \`${reference}\``,
           details:
-            `\`${reference}\` dibuang dari stub client (PRD §12.2/§12.3), sehingga nilainya \`undefined\` di browser (crash hydration).\n\n` +
+            `\`${reference}\` dibuang dari stub client, sehingga nilainya \`undefined\` di browser (crash hydration).\n\n` +
             "Sebelum (ditolak):\n" +
             `  const ${reference} = z.object({ … });                 // deklarasi lokal di file yang sama\n` +
             `  export const ${fn.name} = serverFn({ ${kind}: ${reference}, … });\n\n` +
@@ -572,7 +572,7 @@ export function renderServerFnStub(
         code: "E_SERVER_IMPORT_IN_CLIENT",
         file: filename,
         message: `tidak bisa me-resolve \`${reExport.source}\` untuk re-export`,
-        details: "Re-export dari `*.server.ts` harus bisa di-resolve statis (PRD §12.6).",
+        details: "Re-export dari `*.server.ts` harus bisa di-resolve statis.",
         suggestions: ["Perbaiki path re-export", "Hindari re-export dinamis dari file server"],
       });
     }
@@ -595,7 +595,7 @@ export function renderServerFnStub(
         code: "E_SERVER_IMPORT_IN_CLIENT",
         file: filename,
         message: `\`export *\` dari \`${specifier}\` tidak bisa di-resolve`,
-        details: "`export *` dari `*.server.ts` wajib bisa di-expand statis (PRD §12.6).",
+        details: "`export *` dari `*.server.ts` wajib bisa di-expand statis.",
         suggestions: ["Perbaiki path re-export", "Ganti menjadi named re-export"],
       });
     }
@@ -707,7 +707,7 @@ export function nonContractServerFileError(file: string, projectRoot: string): M
   return new MoonsError({
     code: "E_SERVER_IMPORT_IN_CLIENT",
     file: toRelative(projectRoot, file),
-    message: "file server memakai ekstensi di luar kontrak §12",
+    message: "file server memakai ekstensi di luar kontrak `*.server.ts`",
     details:
       "Transform zero-trust hanya menangani `*.server.ts`/`*.server.tsx`; file server dengan ekstensi lain tidak bisa di-stub dan tidak boleh masuk graph client.",
     suggestions: [
@@ -747,7 +747,7 @@ export async function checkClientModuleImports(
       line,
       message: `mengimpor \`${specifier}\` — \`${relApi}\` adalah modul API server-only`,
       details:
-        "`src/api/**` hanya berjalan di server (endpoint HTTP) dan tidak pernah masuk bundle client (PRD Addendum D.1).",
+        "`src/api/**` hanya berjalan di server (endpoint HTTP) dan tidak pernah masuk bundle client.",
       suggestions: [
         "Pindahkan operasi tersebut ke `*.server.ts` dan panggil lewat serverFn",
         "Jangan mengimpor file `src/api` dari route/komponen client",
@@ -892,7 +892,7 @@ export async function checkClientModuleImports(
 
       if (statement.type === "ExportAllDeclaration") {
         if (resolvedTarget === null) {
-          reject(line, `\`export *\` dari \`${targetRelative}\` tidak bisa di-resolve`, "Re-export dari `*.server.ts` wajib bisa di-resolve statis (PRD §12.6).");
+          reject(line, `\`export *\` dari \`${targetRelative}\` tidak bisa di-resolve`, "Re-export dari `*.server.ts` wajib bisa di-resolve statis.");
         }
         continue; // aman: target menjadi stub
       }
@@ -908,7 +908,7 @@ export async function checkClientModuleImports(
         const name = ((item["local"] as AstNode | undefined)?.["name"] as string) ?? "";
         const kind = (item["importKind"] as string | undefined) ?? (statement["importKind"] as string | undefined);
         if (kind === "type") {
-          reject(line, `mengimpor type \`${name}\` dari ${targetRelative}`, "Import dari file server tidak diizinkan di modul client (PRD §12.4).");
+          reject(line, `mengimpor type \`${name}\` dari ${targetRelative}`, "Import dari file server tidak diizinkan di modul client.");
         }
         if (name.length > 0 && !(await isAllowedServerFnImport(resolvedTarget, specifier, name))) {
           reject(
@@ -1029,7 +1029,7 @@ export async function checkClientModuleImports(
 
     const targetRelative =
       resolvedTarget === null ? request.text : toRelative(projectRoot, resolvedTarget);
-    reject(request.node.loc?.start.line ?? 1, `mengimpor (dynamic) \`${request.text}\` dari ${targetRelative}`, "Client tidak boleh melakukan dynamic import ke `*.server.ts` (PRD §12.7).");
+    reject(request.node.loc?.start.line ?? 1, `mengimpor (dynamic) \`${request.text}\` dari ${targetRelative}`, "Client tidak boleh melakukan dynamic import ke `*.server.ts`.");
   }
 
   // `import.meta.glob` yang mencakup `*.server.ts` (§12.7) — audit adversarial M6.
@@ -1060,7 +1060,7 @@ export async function checkClientModuleImports(
         file: relativeFile,
         line: node.loc?.start.line ?? 1,
         message: `mengimpor (glob) \`${pattern}\` di modul client`,
-        details: "`import.meta.glob` yang mencakup `*.server.ts` dilarang di client (PRD §12.7).",
+        details: "`import.meta.glob` yang mencakup `*.server.ts` dilarang di client.",
         suggestions: [
           "Import statis `serverFn` dari `*.server.ts` (hanya itu yang boleh menyeberang), atau",
           "Pindahkan kebutuhan data ke dalam server function",
@@ -1196,7 +1196,7 @@ export function checkRouteModuleExports(context: RouteExportCheckContext): void
       ? ["default", "loader"]
       : base === "_error.tsx" || base === "_404.tsx"
         ? ["default"]
-        : ["default", "loader", "meta", "prerender", "paths"];
+        : ["default", "loader", "meta", "prerender", "paths", "revalidate"];
   const allowedText = `Hanya ${allowed.map((name) => `\`${name}\``).join(", ")} yang boleh di-export.`;
   const relativeFile = toRelative(projectRoot, file);
   const ast = parseModule(code, file);
@@ -1270,7 +1270,7 @@ export function checkRouteModuleExports(context: RouteExportCheckContext): void
       code: "E_ROUTE_EXPORT_INVALID",
       file: relativeFile,
       message: "modul route wajib mengekspor `default`",
-      details: "Setiap file route harus punya `export default` berupa komponen React (PRD §11.2).",
+      details: "Setiap file route harus punya `export default` berupa komponen React.",
       suggestions: ["Tambahkan `export default function Page() { ... }`"],
     });
   }