@moonsjs/vite 0.1.3 → 0.1.5

package/src/server/plugins.ts

@@ -0,0 +1,85 @@
+import { MOONS_VERSION, type App, type Middleware, type MoonsConfig, type RouteDefinition } from "@moonsjs/core";
+
+/**
+ * Eksekusi lifecycle plugin (PRD §14.4 / Addendum B.4).
+ * Urutan: registrasi (addRoute per route → addMiddleware per middleware →
+ * extendContext(register)) → onStart → ready/onReady → shutdown/onShutdown.
+ */
+export interface PluginRuntime {
+  readonly app: App;
+  /** Registrasi + `onStart` (sebelum server siap). */
+  start(): Promise<void>;
+  /** Tandai `app.ready = true` lalu panggil `onReady` (server siap). */
+  ready(): Promise<void>;
+  /** Panggil `onShutdown` (selama drain; error dilaporkan, tidak menggagalkan). */
+  shutdown(): Promise<void>;
+  /** Terapkan extender `extendContext` ke ctx request (dipanggil handler). */
+  applyExtensions(ctx: unknown): void;
+}
+
+export interface PluginRuntimeOptions {
+  config: MoonsConfig;
+  routes: RouteDefinition[];
+  /** Rantai middleware final (config.middleware). */
+  middlewares: Middleware[];
+  log?: (message: string) => void;
+}
+
+export function createPluginRuntime(options: PluginRuntimeOptions): PluginRuntime {
+  const log = options.log ?? ((message: string) => console.warn(message));
+  const plugins = options.config.plugins ?? [];
+  const state = { ready: false, version: MOONS_VERSION };
+  const app = state as App;
+  const extensions: Array<(ctx: unknown) => unknown> = [];
+  const register = (fn: (ctx: unknown) => unknown): void => {
+    extensions.push(fn);
+  };
+
+  // Fase registrasi (sinkron): addRoute → addMiddleware → extendContext.
+  for (const plugin of plugins) {
+    for (const route of options.routes) {
+      // Objek beku: hook bersifat observasi di v1 (lihat docs/decisions/0022).
+      const frozen = Object.freeze({
+        ...route,
+        params: [...route.params],
+      }) as RouteDefinition;
+      plugin.addRoute?.(frozen);
+    }
+    for (const middleware of options.middlewares) {
+      plugin.addMiddleware?.(middleware);
+    }
+    plugin.extendContext?.(register as never);
+  }
+
+  return {
+    app,
+    async start(): Promise<void> {
+      for (const plugin of plugins) {
+        await plugin.onStart?.(app);
+      }
+    },
+    async ready(): Promise<void> {
+      state.ready = true;
+      for (const plugin of plugins) {
+        await plugin.onReady?.(app);
+      }
+    },
+    async shutdown(): Promise<void> {
+      for (const plugin of plugins) {
+        try {
+          await plugin.onShutdown?.(app);
+        } catch (error) {
+          log(`[moons] plugin \`${plugin.name}\` gagal saat onShutdown: ${String(error)}`);
+        }
+      }
+    },
+    applyExtensions(ctx: unknown): void {
+      for (const extend of extensions) {
+        const result = extend(ctx);
+        if (result !== null && typeof result === "object" && !Array.isArray(result)) {
+          Object.assign(ctx as Record<string, unknown>, result);
+        }
+      }
+    },
+  };
+}

package/src/server/prerender.ts

@@ -0,0 +1,230 @@
+import { MoonsError, type RouteDefinition, type RouteModule } from "@moonsjs/core";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { scanPayloadForSecrets } from "../payload-scan";
+
+/**
+ * Prerender statis (PRD Addendum D.5): render route ber-`prerender = true`
+ * saat build → `dist/client/<path>/index.html` (guard: payload scan fail-mode).
+ */
+export interface PrerenderOptions {
+  routes: RouteDefinition[];
+  routesDir: string;
+  loadRoute: Record<string, () => Promise<RouteModule>>;
+  /** Handler SSR yang sudah dibuat runtime (createRequestHandler). */
+  handler: (request: Request) => Promise<Response>;
+  /** Tujuan file statis (biasanya `<root>/dist/client`). */
+  clientDir: string;
+  canary?: string;
+  env?: Record<string, string | undefined>;
+  log?: (message: string) => void;
+}
+
+export interface PrerenderResult {
+  written: number;
+  skipped: number;
+}
+
+/**
+ * Manifest path yang benar-benar di-prerender (dibaca static server agar hanya
+ * file hasil prerender yang "menang" atas SSR — bukan shell index.html biasa).
+ */
+export const PRERENDER_MANIFEST_FILE = "_moons_prerender.json";
+
+export async function runPrerender(options: PrerenderOptions): Promise<PrerenderResult> {
+  const log = options.log ?? ((message: string) => console.log(message));
+  const env = options.env ?? process.env;
+  let written = 0;
+  let skipped = 0;
+  const writtenPaths: string[] = [];
+
+  const pages = options.routes.filter((route) => route.kind === "page");
+  for (const route of pages) {
+    const key = routeKeyOf(options.routesDir, route.file);
+    const load = options.loadRoute[key];
+    if (load === undefined) {
+      continue;
+    }
+    const module = (await load()) as RouteModule;
+    const prerender = module.prerender;
+
+    if (prerender !== true) {
+      if (prerender !== undefined && prerender !== false) {
+        throw prerenderError(route, "`prerender` harus boolean (`true`/`false`)");
+      }
+      continue;
+    }
+
+    const pathnames = await resolvePathnames(route, module);
+    for (const pathname of pathnames) {
+      const response = await options.handler(
+        new Request(`http://localhost${pathname}`, {
+          method: "GET",
+          headers: { "x-moons-prerender": "1" },
+        }),
+      );
+
+      if (response.status === 404) {
+        log(`[moons] prerender: lewati ${pathname} (notFound)`);
+        skipped += 1;
+        continue;
+      }
+      if (response.status >= 300 && response.status < 400) {
+        throw prerenderError(route, `\`redirect()\` tidak didukung saat prerender (${pathname})`);
+      }
+      if (response.status !== 200) {
+        throw prerenderError(route, `status ${response.status} saat merender ${pathname}`);
+      }
+
+      const html = await response.text();
+      const findings = scanPayloadForSecrets(html, {
+        ...(options.canary === undefined ? {} : { canary: options.canary }),
+        env,
+      });
+      if (findings.length > 0) {
+        const labels = findings
+          .map((finding) => (finding.kind === "canary" ? "canary" : `env(${finding.label})`))
+          .join(", ");
+        throw new MoonsError({
+          code: "E_PRERENDER_LEAK",
+          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).",
+          suggestions: [
+            "Jangan mengembalikan nilai env rahasia dari loader yang di-prerender",
+            "Matikan `prerender` untuk route ini atau pindahkan datanya ke serverFn request-time",
+          ],
+        });
+      }
+
+      const file = outputFile(options.clientDir, pathname);
+      mkdirSync(dirname(file), { recursive: true });
+      writeFileSync(file, html);
+      writtenPaths.push(pathname);
+      written += 1;
+    }
+  }
+
+  // Manifest agar static server tahu path mana yang boleh dilayani statis.
+  writeFileSync(
+    join(options.clientDir, PRERENDER_MANIFEST_FILE),
+    `${JSON.stringify({ paths: writtenPaths }, null, 2)}\n`,
+  );
+
+  log(`[moons] prerender selesai: ${written} file (${skipped} dilewati)`);
+  return { written, skipped };
+}
+
+function routeKeyOf(routesDir: string, file: string): string {
+  const relative = file.startsWith(routesDir) ? file.slice(routesDir.length + 1) : file;
+  return relative.split("\\").join("/").replace(/\.(tsx|ts)$/, "");
+}
+
+async function resolvePathnames(route: RouteDefinition, module: RouteModule): Promise<string[]> {
+  const isDynamic = route.params.length > 0;
+  if (!isDynamic) {
+    return [route.path];
+  }
+  const paths = module.paths;
+  if (typeof paths !== "function") {
+    throw new MoonsError({
+      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).",
+      suggestions: [
+        'Tambahkan `export const paths = () => [{ id: "…" }]`',
+        "Atau hapus `prerender` agar dirender SSR saat request",
+      ],
+    });
+  }
+
+  const raw = await (paths as () => unknown | Promise<unknown>)();
+  if (!Array.isArray(raw)) {
+    throw prerenderError(route, "`paths()` harus mengembalikan array");
+  }
+
+  const expected = new Set(route.params);
+  const result: string[] = [];
+  for (const item of raw as unknown[]) {
+    if (item === null || typeof item !== "object" || Array.isArray(item)) {
+      throw prerenderError(route, "item `paths()` harus objek param string");
+    }
+    const record = item as Record<string, unknown>;
+    const keys = Object.keys(record);
+    for (const name of expected) {
+      const value = record[name];
+      if (typeof value !== "string" || value.length === 0) {
+        throw prerenderError(route, `param \`${name}\` wajib string non-kosong`);
+      }
+    }
+    for (const key of keys) {
+      if (!expected.has(key)) {
+        throw prerenderError(route, `param \`${key}\` tidak ada di pola route`);
+      }
+    }
+    result.push(buildPathname(route, record as Record<string, string>));
+  }
+  return result;
+}
+
+function buildPathname(route: RouteDefinition, params: Record<string, string>): string {
+  const segments = route.path.split("/").filter((segment) => segment.length > 0);
+  const out: string[] = [];
+  let catchallName: string | null = null;
+  for (const segment of segments) {
+    if (segment === "*") {
+      catchallName = route.params[route.params.length - 1] ?? null;
+      const value = catchallName === null ? "" : (params[catchallName] ?? "");
+      for (const part of value.split("/")) {
+        if (part.length === 0) {
+          continue;
+        }
+        out.push(encodeSegment(route, part));
+      }
+      continue;
+    }
+    if (segment.startsWith(":")) {
+      out.push(encodeSegment(route, params[segment.slice(1)] ?? ""));
+      continue;
+    }
+    out.push(segment);
+  }
+  return `/${out.join("/")}`;
+}
+
+function encodeSegment(route: RouteDefinition, value: string): string {
+  if (value.length === 0 || /^\.+$/.test(value)) {
+    throw prerenderError(route, `nilai param \`${value}\` tidak valid untuk path file`);
+  }
+  return encodeURIComponent(value);
+}
+
+function outputFile(clientDir: string, pathname: string): string {
+  const parts = pathname.split("/").filter((part) => part.length > 0);
+  const file = resolve(join(clientDir, ...parts, "index.html"));
+  const base = resolve(clientDir);
+  if (file !== base && !file.startsWith(base + sep)) {
+    throw new MoonsError({
+      code: "E_PRERENDER_INVALID",
+      message: `path prerender keluar dari direktori client (\`${pathname}\`)`,
+      details: "Nama file harus berada di dalam `dist/client`.",
+      suggestions: ["Periksa nilai param `paths` — jangan memakai `..`"],
+    });
+  }
+  return file;
+}
+
+function prerenderError(route: RouteDefinition, message: string): MoonsError {
+  return new MoonsError({
+    code: "E_PRERENDER_INVALID",
+    file: route.file,
+    message,
+    details: "Kontrak prerender mengikuti PRD Addendum D.5.",
+    suggestions: [
+      "Perbaiki bentuk `paths`/param agar cocok dengan pola route",
+      "Jangan memakai `redirect()` pada route yang di-prerender",
+    ],
+  });
+}

package/src/server/shell.ts

@@ -3,7 +3,12 @@ import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import type { ViteDevServer } from "vite";
 
-export type Shell = (markup: string, payload: string, url: string) => string | Promise<string>;
+export type Shell = (
+  markup: string,
+  payload: string,
+  url: string,
+  meta?: Record<string, unknown>,
+) => string | Promise<string>;
 
 export const ROOT_PLACEHOLDER = '<div id="root"></div>';
 
@@ -23,8 +28,13 @@ export const DEFAULT_TEMPLATE = [
   "",
 ].join("\n");
 
-/** Inject markup SSR + payload devalue ke shell HTML (PRD §8.2, §17). */
-export function injectShell(template: string, markup: string, payload: string): string {
+/** Inject markup SSR + payload devalue ke shell HTML (PRD §8.2, §17, Addendum B.1). */
+export function injectShell(
+  template: string,
+  markup: string,
+  payload: string,
+  meta?: Record<string, unknown>,
+): string {
   if (!template.includes(ROOT_PLACEHOLDER)) {
     throw new MoonsError({
       code: "E_INTERNAL",
@@ -37,7 +47,51 @@ export function injectShell(template: string, markup: string, payload: string):
     });
   }
   const dataScript = `<script id="__moons_data" type="application/x-moons">${payload}</script>`;
-  return template.replace(ROOT_PLACEHOLDER, `<div id="root">${markup}</div>${dataScript}`);
+  const withRoot = template.replace(ROOT_PLACEHOLDER, `<div id="root">${markup}</div>${dataScript}`);
+  return applyMeta(withRoot, meta);
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+/**
+ * Terapkan meta route ke `<head>` (Addendum B.1): `<title>` + description/og.
+ * Tag yang sudah ada (mis. di index.html) ditimpa; yang belum ada disisipkan
+ * sebelum `</head>`.
+ */
+function applyMeta(html: string, meta: Record<string, unknown> | undefined): string {
+  if (meta === undefined) {
+    return html;
+  }
+  let out = html;
+  if (typeof meta.title === "string") {
+    const title = `<title>${escapeHtml(meta.title)}</title>`;
+    out = /<title>[\s\S]*?<\/title>/.test(out)
+      ? out.replace(/<title>[\s\S]*?<\/title>/, title)
+      : out.replace("</head>", `  ${title}\n</head>`);
+  }
+
+  const tags: Array<{ attr: "name" | "property"; key: string; value: unknown }> = [
+    { attr: "name", key: "description", value: meta.description },
+    { attr: "property", key: "og:title", value: meta.title },
+    { attr: "property", key: "og:description", value: meta.description },
+  ];
+  for (const tag of tags) {
+    if (typeof tag.value !== "string") {
+      continue;
+    }
+    const rendered = `<meta ${tag.attr}="${tag.key}" content="${escapeHtml(tag.value)}" />`;
+    const pattern = new RegExp(`<meta[^>]*${tag.attr}="${tag.key}"[^>]*>`);
+    out = pattern.test(out)
+      ? out.replace(pattern, rendered)
+      : out.replace("</head>", `  ${rendered}\n</head>`);
+  }
+  return out;
 }
 
 /**
@@ -45,11 +99,11 @@ export function injectShell(template: string, markup: string, payload: string):
  * lalu lewatkan ke Vite `transformIndexHtml` (inject `/@vite/client`, dsb).
  */
 export function createDevShell(server: ViteDevServer, options: { templatePath: string }): Shell {
-  return async (markup, payload, url) => {
+  return async (markup, payload, url, meta) => {
     const template = existsSync(options.templatePath)
       ? readFileSync(options.templatePath, "utf8")
       : DEFAULT_TEMPLATE;
-    const html = injectShell(template, markup, payload);
+    const html = injectShell(template, markup, payload, meta);
     return await server.transformIndexHtml(url, html);
   };
 }
@@ -57,7 +111,7 @@ export function createDevShell(server: ViteDevServer, options: { templatePath: s
 /** Shell untuk produksi: baca `dist/client/index.html` sekali dari cwd. */
 export function createFileShell(options: { clientDir?: string } = {}): Shell {
   let cached: string | null = null;
-  return async (markup, payload) => {
+  return async (markup, payload, _url, meta) => {
     if (cached === null) {
       const clientDir = resolve(options.clientDir ?? process.cwd(), "dist/client");
       const file = join(clientDir, "index.html");
@@ -72,6 +126,6 @@ export function createFileShell(options: { clientDir?: string } = {}): Shell {
       }
       cached = readFileSync(file, "utf8");
     }
-    return injectShell(cached, markup, payload);
+    return injectShell(cached, markup, payload, meta);
   };
 }

package/src/server/shutdown.ts

@@ -6,6 +6,12 @@ export interface ShutdownOptions {
   log?: (message: string) => void;
   /** Injectable untuk test; default `process.exit`. */
   exit?: (code: number) => void;
+  /**
+   * Dipanggil setelah drain penuh, sebelum exit (Addendum B.4: onShutdown
+   * plugin). Berbagi batas waktu dengan drain; error dilaporkan, tidak
+   * menggagalkan shutdown.
+   */
+  onShutdown?: () => void | Promise<void>;
 }
 
 /**
@@ -50,13 +56,24 @@ export function installGracefulShutdown(
       // abaikan: fallback timeout tetap ada
     }
 
-    server.close((error?: Error) => {
-      clearTimeout(timer);
+    server.close(async (error?: Error) => {
       if (error !== undefined) {
+        clearTimeout(timer);
         log(`[moons] penutupan server gagal: ${error.message}`);
         exit(1);
         return;
       }
+      if (options.onShutdown !== undefined) {
+        // Tetap berbagi batas waktu dengan drain: timer di-ref kembali agar
+        // proses tidak keluar sebelum hook selesai.
+        (timer as { ref?: () => void }).ref?.();
+        try {
+          await options.onShutdown();
+        } catch (hookError) {
+          log(`[moons] onShutdown gagal: ${String(hookError)}`);
+        }
+      }
+      clearTimeout(timer);
       log("[moons] shutdown selesai (drain penuh)");
       exit(0);
     });

package/src/server/test-server.ts

@@ -26,7 +26,8 @@ export function createTestServer(
   baseUrl = "http://localhost",
 ): TestServer {
   const shell: Shell =
-    options.shell ?? ((markup, payload) => injectShell(DEFAULT_TEMPLATE, markup, payload));
+    options.shell ??
+    ((markup, payload, _url, meta) => injectShell(DEFAULT_TEMPLATE, markup, payload, meta));
 
   const handler = createRequestHandler({
     routes: options.routes,

package/src/server-only.ts

@@ -0,0 +1,220 @@
+import { MoonsError } from "@moonsjs/core";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/**
+ * Gate paket server-only (PRD Addendum C): paket npm yang tidak boleh masuk
+ * graph client — di-import dari route/client/shared → build gagal.
+ *
+ * Daftar bawaan adalah **minimum normatif** dan TIDAK dapat dihapus app:
+ * gate kebocoran tidak boleh bisa dilonggarkan (prinsip "batas lebih ketat
+ * menang"); salah-tangkap diperbaiki lewat rilis framework.
+ */
+export const DEFAULT_SERVER_ONLY_PACKAGES: ReadonlyArray<string> = [
+  "pg",
+  "postgres",
+  "mysql",
+  "mysql2",
+  "sqlite3",
+  "better-sqlite3",
+  "drizzle-orm",
+  "@prisma/client",
+  "prisma",
+  "mongodb",
+  "mongoose",
+  "redis",
+  "ioredis",
+  "bcrypt",
+  "bcryptjs",
+  "argon2",
+  "jsonwebtoken",
+  "nodemailer",
+  "sharp",
+  "execa",
+  "cross-spawn",
+  "dotenv",
+  "knex",
+  "typeorm",
+  "sequelize",
+  "@libsql/client",
+];
+
+export type ServerOnlyMatchSource = "builtin" | "config" | "marker";
+
+export interface PackageJsonInfo {
+  /** Direktori package (tempat package.json berada). */
+  dir: string;
+  name: string;
+  serverOnlyMarker: boolean;
+}
+
+export interface ServerOnlyMatch {
+  packageName: string;
+  source: ServerOnlyMatchSource;
+  packageDir: string;
+}
+
+export interface ServerOnlyClassifier {
+  check(input: {
+    specifier: string;
+    resolvedFile: string | null;
+    importerFile: string;
+  }): ServerOnlyMatch | null;
+}
+
+export interface ServerOnlyClassifierOptions {
+  /** `security.serverOnlyPackages` — tambahan milik app (tidak menghapus bawaan). */
+  configured?: ReadonlyArray<string>;
+  /** Cache package.json per-direktori; bagikan lintas modul demi performa. */
+  cache?: Map<string, PackageJsonInfo | null>;
+}
+
+/** Nama paket dari specifier bare (dipakai sebagai info pelengkap; pencocokan utama lewat resolve). */
+export function packageNameFromSpecifier(specifier: string): string | null {
+  if (
+    specifier.length === 0 ||
+    specifier.startsWith(".") ||
+    specifier.startsWith("/") ||
+    specifier.startsWith("\0") ||
+    specifier.includes(":")
+  ) {
+    return null;
+  }
+  const parts = specifier.split("/");
+  if (specifier.startsWith("@")) {
+    if (parts.length < 2 || (parts[1] ?? "").length === 0) {
+      return null;
+    }
+    return `${parts[0]}/${parts[1]}`;
+  }
+  return parts[0] ?? null;
+}
+
+/** Baca package.json pada direktori tertentu (null bila tidak ada/gagal). */
+export function tryReadPackageJson(dir: string): PackageJsonInfo | null {
+  const candidate = join(dir, "package.json");
+  if (!existsSync(candidate)) {
+    return null;
+  }
+  try {
+    const json = JSON.parse(readFileSync(candidate, "utf8")) as {
+      name?: unknown;
+      moons?: unknown;
+    };
+    const moons = json.moons as { serverOnly?: unknown } | undefined;
+    return {
+      dir,
+      name: typeof json.name === "string" ? json.name : "",
+      serverOnlyMarker: moons?.serverOnly === true,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Baca package.json terdekat dari sebuah file absolut (menelusuri ke atas). */
+export function readPackageJsonFrom(file: string): PackageJsonInfo | null {
+  let dir = dirname(file);
+  for (let depth = 0; depth < 64; depth += 1) {
+    const info = tryReadPackageJson(dir);
+    if (info !== null) {
+      return info;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return null;
+    }
+    dir = parent;
+  }
+  return null;
+}
+
+export function createServerOnlyClassifier(
+  options: ServerOnlyClassifierOptions = {},
+): ServerOnlyClassifier {
+  const cache = options.cache ?? new Map<string, PackageJsonInfo | null>();
+  const configured = new Set(options.configured ?? []);
+  const builtin = new Set(DEFAULT_SERVER_ONLY_PACKAGES);
+
+  const infoOf = (file: string): PackageJsonInfo | null => {
+    let dir = dirname(file);
+    for (let depth = 0; depth < 64; depth += 1) {
+      if (cache.has(dir)) {
+        return cache.get(dir) ?? null;
+      }
+      const info = tryReadPackageJson(dir);
+      if (info !== null) {
+        cache.set(dir, info);
+        return info;
+      }
+      // Direktori tanpa package.json: lanjut ke atas (tidak di-cache agar
+      // penelusuran berikutnya tetap benar untuk subtree berbeda).
+      const parent = dirname(dir);
+      if (parent === dir) {
+        return null;
+      }
+      dir = parent;
+    }
+    return null;
+  };
+
+  return {
+    check({ specifier: _specifier, resolvedFile, importerFile }) {
+      if (resolvedFile === null) {
+        return null;
+      }
+      const info = infoOf(resolvedFile);
+      if (info === null || info.name.length === 0) {
+        return null;
+      }
+      // Gate menyasar dependency: import di dalam package yang sama diabaikan.
+      const importer = infoOf(importerFile);
+      if (importer !== null && importer.dir === info.dir) {
+        return null;
+      }
+      if (builtin.has(info.name)) {
+        return { packageName: info.name, source: "builtin", packageDir: info.dir };
+      }
+      if (configured.has(info.name)) {
+        return { packageName: info.name, source: "config", packageDir: info.dir };
+      }
+      if (info.serverOnlyMarker) {
+        return { packageName: info.name, source: "marker", packageDir: info.dir };
+      }
+      return null;
+    },
+  };
+}
+
+/**
+ * Error §15 untuk import paket server-only (kode tetap
+ * `E_FORBIDDEN_SERVER_IMPORT`, PRD Addendum C.3).
+ */
+export function serverOnlyImportError(input: {
+  relativeFile: string;
+  line: number;
+  specifier: string;
+  packageName: string;
+  source: ServerOnlyMatchSource;
+  /** Path package.json relatif project — untuk sumber kecocokan "marker". */
+  markerPath?: string;
+  dynamic?: boolean;
+}): MoonsError {
+  const sourceLabel =
+    input.source === "builtin"
+      ? "Sumber kecocokan: daftar bawaan paket server-only framework."
+      : input.source === "config"
+        ? "Sumber kecocokan: `security.serverOnlyPackages` di moons.config.ts."
+        : `Sumber kecocokan: marker \`"moons": { "serverOnly": true }\` di ${input.markerPath ?? "package.json"}.`;
+  return new MoonsError({
+    code: "E_FORBIDDEN_SERVER_IMPORT",
+    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).`,
+    suggestions: [
+      "Pindahkan operasi tersebut ke `*.server.ts` dan panggil lewat serverFn",
+      "Atau ganti/hapus import tersebut di modul client",
+    ],
+  });
+}