mintiljs 0.1.0

package/src/core/routes.ts

@@ -0,0 +1,247 @@
+import path from "node:path";
+import React from "react";
+import type { Hono } from "hono";
+import type { Context } from "hono";
+import { renderPage } from "../render/ssr.tsx";
+import { tryStreamPage } from "../render/stream.tsx";
+import { resetIslands, getUsedIslands, getIslandDef } from "../render/island.tsx";
+import {
+  collectApiMiddlewares,
+  collectApiRoutes,
+  collectPageLayouts,
+  collectPageRoutes,
+  loadRootMiddleware,
+} from "../router/index.ts";
+import type { ApiMiddleware, ApiRoute, PageLayout, PageRoute } from "../router/index.ts";
+import { pagePropsFromContext } from "../router/pages.ts";
+import type { MintilMiddleware } from "../types/middleware.ts";
+import type { ResolvedConfig } from "../types/config.ts";
+import type { PageComponent } from "../types/page.ts";
+import { buildClientBundle, getFrameworkBundle, getFrameworkRoute, getSourceMap, getClientCacheKey } from "./client.ts";
+import { loadAndRegisterIslands, buildIslandBundle } from "./islands.ts";
+import { loadMessages, i18nDirectoryExists } from "../i18n/loader.ts";
+
+
+export async function registerRootMiddleware(
+  app: Hono,
+  root: string,
+  nonce?: string,
+): Promise<void> {
+  const mw: MintilMiddleware | null = await loadRootMiddleware(root, nonce);
+  if (mw) (app as any).use(mw);
+}
+
+export async function collectRoutes(root: string, nonce?: string) {
+  const [apiRoutes, apiMiddlewares, pageRoutes, pageLayouts] = await Promise.all([
+    collectApiRoutes(root, nonce),
+    collectApiMiddlewares(root, nonce),
+    collectPageRoutes(root, nonce),
+    collectPageLayouts(root, nonce),
+  ]);
+  return { apiRoutes, apiMiddlewares, pageRoutes, pageLayouts };
+}
+
+export function registerApiRoutes(
+  app: Hono,
+  apiRoutes: ApiRoute[],
+  apiMiddlewares: ApiMiddleware[],
+) {
+  for (const api of apiRoutes) {
+    const activeMiddlewares = apiMiddlewares.filter((m) => isRoutePrefix(api.route, m.route));
+    const middlewareFns = activeMiddlewares.map((m) => m.middleware);
+
+    if (activeMiddlewares.length > 0) {
+      const mwList = activeMiddlewares.map((m) => `${m.route} (${path.basename(m.file)})`).join(", ");
+      console.log(`  [middleware] ${api.route} <- ${mwList}`);
+    }
+
+    for (const { method, handler } of api.handlers) {
+      // Hono's app.on accepts any HTTP method and a list of handlers.
+      (app as any).on(method, api.route, ...middlewareFns, handler);
+    }
+  }
+}
+
+export async function registerI18nRoute(
+  app: Hono,
+  root: string,
+) {
+  const exists = await i18nDirectoryExists(root);
+  if (!exists) return;
+  app.get("/_mintil/i18n/:locale", async (c: Context) => {
+    const locale = c.req.param("locale") || "";
+    const messages = await loadMessages(root, locale);
+    return c.json(messages);
+  });
+  console.log("  [i18n] /_mintil/i18n/:locale");
+}
+
+export async function registerPageRoutes(
+  app: Hono,
+  pageRoutes: PageRoute[],
+  pageLayouts: PageLayout[],
+  resolved: ResolvedConfig,
+  nonce?: string,
+) {
+  // Build the shared framework bundle once (React + ReactDOM) and register its route.
+  const frameworkJs = await getFrameworkBundle();
+  const frameworkUrl = frameworkJs ? await getFrameworkRoute() : undefined;
+  if (frameworkUrl) {
+    app.get(frameworkUrl, (c: Context) => {
+      return c.text(frameworkJs!, 200, { "Content-Type": "application/javascript" });
+    });
+  }
+
+  // Load and register island components from filesystem
+  await loadAndRegisterIslands(resolved.root);
+
+  // Register a single dynamic endpoint for island bundles
+  // Builds and caches on first request per island
+  const islandBundleCache = new Map<string, string>();
+  app.get("/_mintil/islands/:name", async (c: Context) => {
+    const raw = c.req.param("name") || "";
+    const name = raw.replace(/\.js$/i, "");
+    if (islandBundleCache.has(name)) {
+      return c.text(islandBundleCache.get(name)!, 200, { "Content-Type": "application/javascript" });
+    }
+    const def = getIslandDef(name);
+    if (!def) {
+      return c.text(`console.error("[mintil] island '${name}' not found")`, 404, {
+        "Content-Type": "application/javascript",
+      });
+    }
+    const js = await buildIslandBundle(name, def.file, { mode: resolved.mode });
+    if (!js) {
+      return c.text(`console.error("[mintil] failed to build island '${name}'")`, 500, {
+        "Content-Type": "application/javascript",
+      });
+    }
+    islandBundleCache.set(name, js);
+    return c.text(js, 200, { "Content-Type": "application/javascript" });
+  });
+
+  for (const page of pageRoutes) {
+    const layout = pickLayout(page.route, pageLayouts);
+
+    let clientBundle: string | null = null;
+    let clientBundleName: string | null = null;
+    if (page.useClient && frameworkJs) {
+      const js = await buildClientBundle(page.file, page.route, { mode: resolved.mode });
+      if (js) {
+        const bundleName = routeToBundleName(page.route);
+        clientBundleName = bundleName;
+        clientBundle = `/_mintil/client/${bundleName}.js`;
+        app.get(clientBundle, (c: Context) => {
+          return c.text(js, 200, { "Content-Type": "application/javascript" });
+        });
+        // Serve source map in development mode
+        if (resolved.mode === "development") {
+          app.get(`/_mintil/client/${bundleName}.js.map`, (c: Context) => {
+            const map = getSourceMap(getClientCacheKey(page.route));
+            if (!map) return c.notFound();
+            return c.text(map, 200, { "Content-Type": "application/json" });
+          });
+        }
+        console.log(`  [client] ${page.route} -> ${clientBundle}`);
+      }
+    }
+
+    app.get(page.route, async (c: Context) => {
+      resetIslands();
+
+      const props = pagePropsFromContext(c);
+
+      let extraProps: Record<string, any> | undefined;
+      if (page.getServerSideProps) {
+        try {
+          const result = await page.getServerSideProps({
+            params: props.params,
+            searchParams: props.searchParams,
+            req: c.req.raw,
+          });
+          if (result && typeof result.props === "object") {
+            extraProps = result.props;
+          }
+        } catch (err) {
+          console.error(`[mintil] getServerSideProps error for ${page.route}:`, err);
+        }
+      }
+
+      const pageOpts = {
+        root: resolved.root,
+        route: page.route,
+        params: props.params,
+        searchParams: props.searchParams,
+        mode: resolved.mode,
+        nonce,
+        layout,
+        clientBundle: clientBundle ?? undefined,
+        frameworkUrl,
+        extraProps,
+      };
+
+      // Quick sync pass to detect used islands
+      resetIslands();
+      const React = await import("react");
+      const { renderToString } = await import("react-dom/server");
+      const quickElement = buildQuickElement(page.component, pageOpts, layout);
+      try { renderToString(quickElement); } catch {}
+
+      const usedIslands = getUsedIslands();
+      const needsIslands = usedIslands.length > 0;
+
+      if (!clientBundle && !needsIslands) {
+        // No client bundle and no islands — try streaming
+        const streamResponse = await tryStreamPage(page.component, pageOpts);
+        if (streamResponse) return streamResponse;
+      }
+
+      // Sync render with island scripts if needed
+      const islandScripts: string[] = needsIslands
+        ? usedIslands.map((name) => `<script type="module" src="/_mintil/islands/${name}.js"></script>`)
+        : [];
+
+      const html = await renderPage(page.component, {
+        ...pageOpts,
+        islandScripts: islandScripts.length > 0 ? islandScripts : undefined,
+      });
+      return c.html(html);
+    });
+  }
+}
+
+function routeToBundleName(route: string): string {
+  return (
+    route
+      .replace(/^\/+/g, "")
+      .replace(/\/+/g, "_")
+      .replace(/[^a-zA-Z0-9_\-]/g, "_") || "index"
+  );
+}
+
+function isRoutePrefix(route: string, prefix: string): boolean {
+  if (prefix === "/") return true;
+  return route === prefix || route.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`);
+}
+
+function pickLayout(
+  pageRoute: string,
+  layouts: PageLayout[],
+): PageLayout["component"] | undefined {
+  for (const layout of layouts) {
+    if (isRoutePrefix(pageRoute, layout.scope)) {
+      return layout.component;
+    }
+  }
+  return undefined;
+}
+
+function buildQuickElement(
+  Page: PageComponent,
+  opts: { params: Record<string, string>; searchParams: URLSearchParams; extraProps?: Record<string, any> },
+  layout: PageLayout["component"] | undefined,
+) {
+  const pageProps = { params: opts.params, searchParams: opts.searchParams, ...opts.extraProps };
+  const pageEl = React.createElement("div", { id: "__mintil-root" }, React.createElement(Page, pageProps));
+  return layout ? React.createElement(layout, { children: pageEl }) : pageEl;
+}

package/src/core/runtime.ts

@@ -0,0 +1,131 @@
+import path from "node:path";
+import { Hono } from "hono";
+import type { Hono as HonoType } from "hono";
+import fs from "node:fs/promises";
+import { logMiddleware } from "./logger.ts";
+import { resolveConfig } from "./config.ts";
+import { getLocalIp } from "../utils/network.ts";
+import { watchRoot, closeWatchers } from "./watcher.ts";
+import { registerRootMiddleware, collectRoutes, registerApiRoutes, registerPageRoutes, registerI18nRoute } from "./routes.ts";
+import { processCss } from "./css.ts";
+import type { MintilConfig } from "../types/config.ts";
+
+let started = false;
+
+export async function createMintilApp(
+  config?: MintilConfig,
+  nonce?: string,
+  serverRef?: { current: ReturnType<typeof Bun.serve> | null },
+): Promise<HonoType> {
+  const resolved = resolveConfig(
+    path.resolve(config?.root ?? process.cwd()),
+    config,
+  );
+
+  const app = new Hono();
+
+  app.use(logMiddleware(serverRef));
+
+  // User-supplied root middleware must be registered before routes.
+  await registerRootMiddleware(app, resolved.root, nonce);
+
+  app.get("/styles.css", async (c) => {
+    const css = await processCss(resolved.root, resolved.mode);
+    return c.text(css, 200, { "Content-Type": "text/css" });
+  });
+
+  app.get("/assets/*", async (c) => {
+    const subpath = c.req.path.replace(/^\/assets\//, "");
+    const filePath = path.join(resolved.root, "public", subpath);
+    if (!filePath.startsWith(path.join(resolved.root, "public"))) {
+      return c.notFound();
+    }
+    try {
+      const file = Bun.file(filePath);
+      if (!(await file.exists())) return c.notFound();
+      return new Response(file);
+    } catch {
+      return c.notFound();
+    }
+  });
+
+  // Auto-register i18n API if i18n/messages directory exists
+  await registerI18nRoute(app, resolved.root);
+
+  const { apiRoutes, apiMiddlewares, pageRoutes, pageLayouts } = await collectRoutes(
+    resolved.root,
+    nonce,
+  );
+  registerApiRoutes(app, apiRoutes, apiMiddlewares);
+  await registerPageRoutes(app, pageRoutes, pageLayouts, resolved, nonce);
+
+  // Apply plugins
+  for (const plugin of resolved.plugins) {
+    try {
+      await plugin.setup(app, resolved);
+      console.log(`  [plugin] ${plugin.name} registered`);
+    } catch (err) {
+      console.error(`[mintil] plugin "${plugin.name}" setup error:`, err);
+    }
+  }
+
+  return app;
+}
+
+export async function start(config?: MintilConfig): Promise<ReturnType<typeof Bun.serve>> {
+  if (started) {
+    throw new Error("Mintil runtime has already been started.");
+  }
+  started = true;
+
+  const resolved = resolveConfig(
+    path.resolve(config?.root ?? process.cwd()),
+    config,
+  );
+
+  let nonce = String(Date.now());
+  const serverRef: { current: ReturnType<typeof Bun.serve> | null } = { current: null };
+  let app = await createMintilApp(config, nonce, serverRef);
+
+  const hostname = resolved.host ? "0.0.0.0" : "127.0.0.1";
+  const displayHost = resolved.host ? "0.0.0.0" : "localhost";
+  const localIp = resolved.host ? getLocalIp() : null;
+
+  console.log(
+    `Mintil runtime starting in ${resolved.mode} mode at http://${displayHost}:${resolved.port}`,
+  );
+  if (localIp) {
+    console.log(`Network:        http://${localIp}:${resolved.port}`);
+  }
+
+  const server = Bun.serve({
+    hostname,
+    port: resolved.port,
+    fetch: app.fetch,
+  });
+
+  serverRef.current = server;
+
+  if (resolved.mode === "development") {
+    watchRoot(resolved.root, async () => {
+      nonce = String(Date.now());
+      try {
+        app = await createMintilApp(config, nonce, serverRef);
+        server.reload({ fetch: app.fetch });
+        console.log("[mintil] project reloaded");
+      } catch (err) {
+        console.error("[mintil] reload failed", err);
+      }
+    });
+  }
+
+  process.on("exit", () => {
+    closeWatchers();
+  });
+
+  return server;
+}
+
+export function resetStarted() {
+  started = false;
+}

package/src/core/watcher.ts

@@ -0,0 +1,43 @@
+import { watch } from "node:fs";
+
+const activeWatchers: ReturnType<typeof watch>[] = [];
+
+export function closeWatchers() {
+  for (const watcher of activeWatchers) {
+    try {
+      watcher.close();
+    } catch {
+      // ignore
+    }
+  }
+  activeWatchers.length = 0;
+}
+
+export function watchRoot(root: string, onChange: () => void) {
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+
+  const watcher = watch(
+    root,
+    { recursive: true },
+    (_event, filename) => {
+      if (!filename) return;
+      if (
+        filename.includes("node_modules") ||
+        filename.includes(".git") ||
+        filename.includes("bun.lock")
+      ) {
+        return;
+      }
+      if (timeout) clearTimeout(timeout);
+      timeout = setTimeout(() => {
+        onChange();
+      }, 150);
+    },
+  );
+
+  activeWatchers.push(watcher);
+
+  watcher.on("error", (err) => {
+    console.error("[mintil] file watcher error", err);
+  });
+}

package/src/i18n/index.ts

@@ -0,0 +1,57 @@
+import type { i18nMessage, i18nOptions } from "./types.ts";
+import { loadMessages, clearCache } from "./loader.ts";
+
+const I18N_API_PATH = "/_mintil/i18n";
+
+function isBrowser(): boolean {
+  return typeof globalThis !== "undefined" && typeof (globalThis as any).window !== "undefined" && typeof (Bun as any) === "undefined";
+}
+
+function getRoot(options?: i18nOptions): string {
+  return options?.root ?? (typeof process !== "undefined" && process.cwd ? process.cwd() : "");
+}
+
+/**
+ * Load messages for the given locale.
+ *
+ * On the server (Bun), reads from `i18n/messages/[locale].json` or
+ * `i18n/messages/[locale]/` (numbered split files).
+ *
+ * In the browser, fetches from the auto-registered `/_mintil/i18n/:locale` endpoint.
+ *
+ * @param locale - Locale string (e.g. `"en"`, `"pt-BR"`).
+ * @param options - Optional root directory override.
+ *
+ * @example
+ * ```ts
+ * import { getMessages } from "mintiljs/i18n";
+ *
+ * const msgs = await getMessages("en");
+ * // msgs = [{ key: "greeting", value: "Hello" }, ...]
+ * ```
+ */
+export async function getMessages(
+  locale: string,
+  options?: i18nOptions,
+): Promise<i18nMessage[]> {
+  if (isBrowser()) {
+    return fetchMessagesFromServer(locale);
+  }
+  const root = getRoot(options);
+  return loadMessages(root, locale);
+}
+
+async function fetchMessagesFromServer(locale: string): Promise<i18nMessage[]> {
+  try {
+    const base = (globalThis as any).location?.origin ?? "";
+    const res = await fetch(`${base}${I18N_API_PATH}/${locale}`);
+    if (!res.ok) return [];
+    return res.json() as Promise<i18nMessage[]>;
+  } catch {
+    return [];
+  }
+}
+
+export type { i18nMessage, i18nOptions, i18nPlaceholders } from "./types.ts";
+export { loadMessages, clearCache } from "./loader.ts";
+export { format, toObject, t, createTranslate } from "./translate.ts";

package/src/i18n/loader.ts

@@ -0,0 +1,125 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import type { i18nMessage } from "./types.ts";
+
+const cache = new Map<string, i18nMessage[]>();
+
+function flattenObject(
+  obj: Record<string, any>,
+  prefix = "",
+): i18nMessage[] {
+  const result: i18nMessage[] = [];
+  for (const [key, value] of Object.entries(obj)) {
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+    if (typeof value === "string") {
+      result.push({ key: fullKey, value });
+    } else if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      result.push(...flattenObject(value, fullKey));
+    }
+  }
+  return result;
+}
+
+async function loadSingleFile(
+  filePath: string,
+): Promise<i18nMessage[] | null> {
+  try {
+    const raw = await fs.readFile(filePath, "utf-8");
+    const obj = JSON.parse(raw);
+    return flattenObject(obj);
+  } catch {
+    return null;
+  }
+}
+
+async function loadDirectory(
+  dirPath: string,
+): Promise<i18nMessage[]> {
+  const entries = await fs.readdir(dirPath, { withFileTypes: true });
+  const jsonFiles = entries
+    .filter((e) => e.isFile() && e.name.endsWith(".json"))
+    .sort((a, b) => a.name.localeCompare(b.name, undefined, { numeric: true }));
+
+  const all: i18nMessage[] = [];
+  for (const file of jsonFiles) {
+    const filePath = path.join(dirPath, file.name);
+    const messages = await loadSingleFile(filePath);
+    if (messages) all.push(...messages);
+  }
+  return all;
+}
+
+export async function loadMessages(
+  root: string,
+  locale: string,
+): Promise<i18nMessage[]> {
+  const cacheKey = `${root}:${locale}`;
+  const cached = cache.get(cacheKey);
+  if (cached) return cached;
+
+  const i18nDir = path.join(root, "i18n", "messages");
+
+  // Try single file: i18n/messages/[locale].json
+  const singlePath = path.join(i18nDir, `${locale}.json`);
+  const fromFile = await loadSingleFile(singlePath);
+  if (fromFile) {
+    cache.set(cacheKey, fromFile);
+    return fromFile;
+  }
+
+  // Try directory: i18n/messages/[locale]/
+  const dirPath = path.join(i18nDir, locale);
+  try {
+    const stat = await fs.stat(dirPath);
+    if (stat.isDirectory()) {
+      const fromDir = await loadDirectory(dirPath);
+      cache.set(cacheKey, fromDir);
+      return fromDir;
+    }
+  } catch {
+    // directory does not exist
+  }
+
+  return [];
+}
+
+export async function getMessagesFileList(
+  root: string,
+): Promise<string[]> {
+  const i18nDir = path.join(root, "i18n", "messages");
+  try {
+    const entries = await fs.readdir(i18nDir, { withFileTypes: true });
+    const locales: string[] = [];
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith(".json")) {
+        locales.push(entry.name.replace(/\.json$/, ""));
+      } else if (entry.isDirectory()) {
+        locales.push(entry.name);
+      }
+    }
+    return locales;
+  } catch {
+    return [];
+  }
+}
+
+export async function i18nDirectoryExists(root: string): Promise<boolean> {
+  try {
+    const stat = await fs.stat(path.join(root, "i18n"));
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function clearCache(root?: string, locale?: string) {
+  if (root && locale) {
+    cache.delete(`${root}:${locale}`);
+  } else if (root) {
+    for (const key of cache.keys()) {
+      if (key.startsWith(`${root}:`)) cache.delete(key);
+    }
+  } else {
+    cache.clear();
+  }
+}

package/src/i18n/translate.ts

@@ -0,0 +1,89 @@
+import type { i18nMessage, i18nPlaceholders } from "./types.ts";
+
+const PLACEHOLDER_RE = /\{(\w+)\}/g;
+
+/**
+ * Replace `{key}` placeholders in a template string with values from `placeholders`.
+ *
+ * @param template - String containing `{key}` placeholders.
+ * @param placeholders - Object mapping keys to replacement values.
+ *
+ * @example
+ * ```ts
+ * format("Hello, {name}!", { name: "John" })
+ * // => "Hello, John!"
+ * ```
+ */
+export function format(
+  template: string,
+  placeholders: i18nPlaceholders,
+): string {
+  return template.replace(PLACEHOLDER_RE, (_, key: string) => {
+    const val = placeholders[key];
+    return val !== undefined ? String(val) : `{${key}}`;
+  });
+}
+
+/**
+ * Convert a flat `i18nMessage[]` array to a `Record<string, string>`.
+ *
+ * Useful for fast lookups and passing messages to client-side components.
+ *
+ * @example
+ * ```ts
+ * const map = toObject(msgs);
+ * map.greeting // "Hello"
+ * ```
+ */
+export function toObject(messages: i18nMessage[]): Record<string, string> {
+  const obj: Record<string, string> = {};
+  for (const m of messages) obj[m.key] = m.value;
+  return obj;
+}
+
+/**
+ * Translate a message by key, optionally applying placeholders.
+ *
+ * Returns the raw message value if no placeholders given,
+ * or the formatted string with placeholders substituted.
+ *
+ * @param messages - Array of messages from `getMessages`.
+ * @param key - The message key to look up.
+ * @param placeholders - Optional key-value pairs for `{key}` substitution.
+ *
+ * @example
+ * ```ts
+ * const msgs = await getMessages("en");
+ *
+ * t(msgs, "greeting")                      // "Hello"
+ * t(msgs, "welcome", { name: "John" })     // "Welcome, John!"
+ * t(msgs, "missing")                       // "missing" (key not found)
+ * ```
+ */
+export function t(
+  messages: i18nMessage[],
+  key: string,
+  placeholders?: i18nPlaceholders,
+): string {
+  for (const m of messages) {
+    if (m.key === key) {
+      return placeholders ? format(m.value, placeholders) : m.value;
+    }
+  }
+  return key;
+}
+
+/**
+ * Wraps a messages object (Record) with a `t` function for convenient use in components.
+ *
+ * @example
+ * ```ts
+ * const msg = createTranslate(msgs);
+ * msg("greeting")                        // "Hello"
+ * msg("welcome", { name: "John" })       // "Welcome, John!"
+ * ```
+ */
+export function createTranslate(messages: i18nMessage[]) {
+  return (key: string, placeholders?: i18nPlaceholders) =>
+    t(messages, key, placeholders);
+}

package/src/i18n/types.ts

@@ -0,0 +1,10 @@
+export interface i18nMessage {
+  key: string;
+  value: string;
+}
+
+export interface i18nOptions {
+  root?: string;
+}
+
+export type i18nPlaceholders = Record<string, string | number>;