@octanejs/vite-plugin 0.1.1

package/src/server/production.js

@@ -0,0 +1,26 @@
+/**
+ * Production fetch-handler factory + config re-exports.
+ *
+ * PHASE 1 STUB. `createHandler` is the runtime entry the generated server
+ * bundle calls in production; it is wired in Phase 2 (async render, adapter
+ * `serve`, asset preload, RPC). Until then it throws a clear error. The
+ * `./production` export path stays resolvable, and `resolveOctaneConfig` is
+ * re-exported here because the generated server entry imports it from this
+ * module (mirrors @ripple-ts/vite-plugin).
+ */
+
+export { resolveOctaneConfig } from '../load-config.js';
+
+/**
+ * Create the production fetch handler (Phase 2).
+ *
+ * @param {unknown} _manifest
+ * @param {unknown} _deps
+ * @returns {never}
+ */
+export function createHandler(_manifest, _deps) {
+	throw new Error(
+		'[@octanejs/vite-plugin] Production build (createHandler) is Phase 2 — not yet implemented. ' +
+			'Dev SSR works via `vite dev`.',
+	);
+}

package/src/server/render-route.js

@@ -0,0 +1,214 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createLayoutWrapper, createPropsWrapper } from './component-wrappers.js';
+import {
+	get_component_export,
+	get_route_entry_export_name,
+	get_route_entry_path,
+} from '../routes.js';
+
+/**
+ * @typedef {import('@octanejs/vite-plugin').Context} Context
+ * @typedef {import('@octanejs/vite-plugin').RenderRoute} RenderRoute
+ * @typedef {import('@octanejs/vite-plugin').ResolvedOctaneConfig} ResolvedOctaneConfig
+ * @typedef {import('vite').ViteDevServer} ViteDevServer
+ */
+
+/**
+ * octane RenderResult — `render()` is ASYNC and `css` is ALREADY a deduped
+ * `<style data-octane="hash">…</style>` string (NOT a Set<string> needing a
+ * `get_css_for_hashes` lookup like Ripple). So CSS handling here is identity.
+ *
+ * @typedef {Object} RenderResult
+ * @property {string} head
+ * @property {string} body
+ * @property {string} css
+ */
+
+/**
+ * Handle SSR rendering for a RenderRoute (dev).
+ *
+ * @param {RenderRoute} route
+ * @param {Context} context
+ * @param {ViteDevServer} vite
+ * @param {ResolvedOctaneConfig} [octaneConfig]
+ * @returns {Promise<Response>}
+ */
+export async function handleRenderRoute(route, context, vite, octaneConfig) {
+	try {
+		// Initialize so the server can register RPC functions from `module server`
+		// declarations during SSR module loading (renderer-agnostic; harmless when
+		// the app uses no RPC).
+		if (!(/** @type {any} */ (globalThis).rpc_modules)) {
+			/** @type {any} */ (globalThis).rpc_modules = new Map();
+		}
+
+		// Load the octane server runtime. The wrappers call components directly
+		// (no ssrComponent injection — the root must NOT be marker-wrapped), so
+		// only `render` is needed here.
+		const { render } = await vite.ssrLoadModule('octane/server');
+
+		// Load the page component (compiled in server mode by octane()).
+		const entryPath = get_route_entry_path(route.entry);
+		const pageModule = await vite.ssrLoadModule(/** @type {string} */ (entryPath));
+		const PageComponent = get_component_export(
+			pageModule,
+			get_route_entry_export_name(route.entry),
+		);
+
+		if (!PageComponent) {
+			throw new Error(`No component found for route ${route.path}`);
+		}
+
+		// Build the component tree (with optional layout).
+		let RootComponent;
+		const pageProps = { params: context.params };
+
+		if (route.layout) {
+			const layoutModule = await vite.ssrLoadModule(route.layout);
+			const LayoutComponent = get_component_export(layoutModule, undefined);
+
+			if (!LayoutComponent) {
+				throw new Error(`No default export found in ${route.layout}`);
+			}
+
+			RootComponent = createLayoutWrapper(
+				/** @type {any} */ (LayoutComponent),
+				/** @type {any} */ (PageComponent),
+				pageProps,
+			);
+		} else {
+			RootComponent = createPropsWrapper(/** @type {any} */ (PageComponent), pageProps);
+		}
+
+		// Render to HTML. octane render() is async; head is '' in Phase 1
+		// (no document-head API yet). `body` already contains any inline
+		// <script data-octane-suspense> seed.
+		/** @type {RenderResult} */
+		const { head, body, css } = await render(RootComponent);
+
+		// CSS is already a ready <style> string (or '') — identity, no re-wrapping.
+		const cssContent = css || '';
+
+		// Build head content with hydration data. The client entry is CONFIG-FREE
+		// (importing octane.config.ts into the browser would drag the plugin + the
+		// server adapter — and their `node:fs` imports — into the client graph and
+		// break at module-eval). So everything the client needs to pick + import
+		// the page/layout is serialized HERE: entry path, export name, layout path,
+		// and params. routeIndex stays for debugging / Phase-2 static maps.
+		const routeData = JSON.stringify({
+			entry: entryPath,
+			exportName: get_route_entry_export_name(route.entry) ?? null,
+			layout: route.layout ?? null,
+			routeIndex: getRenderRouteIndex(octaneConfig, route),
+			params: context.params,
+		});
+		const headContent = [
+			head,
+			cssContent,
+			`<script id="__octane_data" type="application/json">${escapeScript(routeData)}</script>`,
+		]
+			.filter(Boolean)
+			.join('\n');
+
+		// Load and process index.html template.
+		const templatePath = join(vite.config.root, 'index.html');
+		let template = await readFile(templatePath, 'utf-8');
+
+		// Apply Vite's HTML transforms (HMR client, module resolution, etc.).
+		template = await vite.transformIndexHtml(context.url.pathname, template);
+
+		// Replace placeholders.
+		let html = template.replace('<!--ssr-head-->', headContent).replace('<!--ssr-body-->', body);
+
+		// Inject the hydration entry before </body>.
+		const hydrationScript = `<script type="module" src="/@id/virtual:octane-hydrate"></script>`;
+		html = html.replace('</body>', `${hydrationScript}\n</body>`);
+
+		return new Response(html, {
+			status: 200,
+			headers: {
+				'Content-Type': 'text/html; charset=utf-8',
+			},
+		});
+	} catch (error) {
+		console.error('[octane] SSR render error:', error);
+
+		const errorHtml = generateErrorHtml(error, route);
+		return new Response(errorHtml, {
+			status: 500,
+			headers: {
+				'Content-Type': 'text/html; charset=utf-8',
+			},
+		});
+	}
+}
+
+/**
+ * @param {ResolvedOctaneConfig | undefined} config
+ * @param {RenderRoute} route
+ * @returns {number | undefined}
+ */
+function getRenderRouteIndex(config, route) {
+	if (!config) {
+		return undefined;
+	}
+	const renderRoutes = config.router.routes.filter((r) => r.type === 'render');
+	const index = renderRoutes.indexOf(route);
+	return index === -1 ? undefined : index;
+}
+
+/**
+ * Escape script content to prevent XSS in the inline JSON data block.
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeScript(str) {
+	return str.replace(/</g, '\\u003c').replace(/>/g, '\\u003e');
+}
+
+/**
+ * Generate an error HTML page for development.
+ *
+ * @param {unknown} error
+ * @param {RenderRoute} route
+ * @returns {string}
+ */
+function generateErrorHtml(error, route) {
+	const message = error instanceof Error ? error.message : String(error);
+	const stack = error instanceof Error ? error.stack : '';
+
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>SSR Error</title>
+<style>
+body { font-family: system-ui, sans-serif; padding: 2rem; background: #1a1a1a; color: #fff; }
+h1 { color: #ff6b6b; }
+pre { background: #2d2d2d; padding: 1rem; border-radius: 4px; overflow-x: auto; }
+.route { color: #888; }
+</style>
+</head>
+<body>
+<h1>SSR Render Error</h1>
+<p class="route">Route: ${route.path} → ${route.entry}</p>
+<pre>${escapeHtml(message)}</pre>
+${stack ? `<pre>${escapeHtml(stack)}</pre>` : ''}
+</body>
+</html>`;
+}
+
+/**
+ * Escape HTML entities.
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeHtml(str) {
+	return str
+		.replace(/&/g, '&amp;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;');
+}

package/src/server/router.js

@@ -0,0 +1,122 @@
+/**
+ * @typedef {import('@octanejs/vite-plugin').Route} Route
+ * @typedef {import('@octanejs/vite-plugin').RenderRoute} RenderRoute
+ * @typedef {import('@octanejs/vite-plugin').ServerRoute} ServerRoute
+ */
+
+/**
+ * @typedef {Object} RouteMatch
+ * @property {Route} route
+ * @property {Record<string, string>} params
+ */
+
+/**
+ * @typedef {Object} CompiledRoute
+ * @property {Route} route
+ * @property {RegExp} pattern
+ * @property {string[]} paramNames
+ * @property {number} specificity - Higher = more specific (static > param > catch-all)
+ */
+
+/**
+ * Convert a route path pattern to a RegExp
+ * Supports:
+ * - Static segments: /about, /api/hello
+ * - Named params: /posts/:id, /users/:userId/posts/:postId
+ * - Catch-all: /docs/*slug
+ *
+ * @param {string} path
+ * @returns {{ pattern: RegExp, paramNames: string[], specificity: number }}
+ */
+function compilePath(path) {
+	/** @type {string[]} */
+	const paramNames = [];
+	let specificity = 0;
+
+	// Escape special regex characters except our param syntax
+	const regexString = path
+		.split('/')
+		.map((segment) => {
+			if (!segment) return '';
+
+			// Catch-all param: *slug
+			if (segment.startsWith('*')) {
+				const paramName = segment.slice(1);
+				paramNames.push(paramName);
+				specificity += 1; // Lowest specificity
+				return '(.+)';
+			}
+
+			// Named param: :id
+			if (segment.startsWith(':')) {
+				const paramName = segment.slice(1);
+				paramNames.push(paramName);
+				specificity += 10; // Medium specificity
+				return '([^/]+)';
+			}
+
+			// Static segment
+			specificity += 100; // Highest specificity
+			return escapeRegex(segment);
+		})
+		.join('/');
+
+	const pattern = new RegExp(`^${regexString || '/'}$`);
+	return { pattern, paramNames, specificity };
+}
+
+/**
+ * Escape special regex characters
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeRegex(str) {
+	return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Create a router from a list of routes
+ * @param {Route[]} routes
+ * @returns {{ match: (method: string, pathname: string) => RouteMatch | null }}
+ */
+export function createRouter(routes) {
+	/** @type {CompiledRoute[]} */
+	const compiledRoutes = routes.map((route) => {
+		const { pattern, paramNames, specificity } = compilePath(route.path);
+		return { route, pattern, paramNames, specificity };
+	});
+
+	// Sort by specificity (higher first) for correct matching order
+	compiledRoutes.sort((a, b) => b.specificity - a.specificity);
+
+	return {
+		/**
+		 * Match a request to a route
+		 * @param {string} method
+		 * @param {string} pathname
+		 * @returns {RouteMatch | null}
+		 */
+		match(method, pathname) {
+			for (const { route, pattern, paramNames } of compiledRoutes) {
+				// Check method for ServerRoute
+				if (route.type === 'server') {
+					const methods = /** @type {ServerRoute} */ (route).methods;
+					if (!methods.includes(method.toUpperCase())) {
+						continue;
+					}
+				}
+
+				const match = pathname.match(pattern);
+				if (match) {
+					/** @type {Record<string, string>} */
+					const params = {};
+					for (let i = 0; i < paramNames.length; i++) {
+						params[paramNames[i]] = decodeURIComponent(match[i + 1]);
+					}
+					return { route, params };
+				}
+			}
+			return null;
+		},
+	};
+}

package/src/server/server-route.js

@@ -0,0 +1,46 @@
+/**
+ * @typedef {import('@octanejs/vite-plugin').Context} Context
+ * @typedef {import('@octanejs/vite-plugin').ServerRoute} ServerRoute
+ * @typedef {import('@octanejs/vite-plugin').Middleware} Middleware
+ */
+
+import { runMiddlewareChain } from './middleware.js';
+
+/**
+ * Handle a ServerRoute (API endpoint)
+ *
+ * @param {ServerRoute} route
+ * @param {Context} context
+ * @param {Middleware[]} globalMiddlewares
+ * @returns {Promise<Response>}
+ */
+export async function handleServerRoute(route, context, globalMiddlewares) {
+	try {
+		// The handler wrapped as a function returning Promise<Response>
+		const handler = async () => {
+			return route.handler(context);
+		};
+
+		// Run the middleware chain: global → before → handler → after
+		const response = await runMiddlewareChain(
+			context,
+			globalMiddlewares,
+			route.before,
+			handler,
+			route.after,
+		);
+
+		return response;
+	} catch (error) {
+		console.error('[octane] API route error:', error);
+
+		// Return error response
+		const message = error instanceof Error ? error.message : 'Internal Server Error';
+		return new Response(JSON.stringify({ error: message }), {
+			status: 500,
+			headers: {
+				'Content-Type': 'application/json',
+			},
+		});
+	}
+}

package/src/server/virtual-entry.js

@@ -0,0 +1,15 @@
+/**
+ * Production server-entry generator.
+ *
+ * PHASE 1 STUB. The generated server entry (imported by the SSR bundle build
+ * in `closeBundle`) wires page/layout/rpc modules into `createHandler`. It is
+ * unused in dev (dev SSR uses `vite.ssrLoadModule`). Implemented in Phase 2.
+ */
+
+/**
+ * @param {unknown} _options
+ * @returns {never}
+ */
+export function generateServerEntry(_options) {
+	throw new Error('[@octanejs/vite-plugin] Server entry generation is Phase 2.');
+}

package/tsconfig.typecheck.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "target": "es2022",
+    "lib": ["esnext", "dom", "dom.iterable"],
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true,
+    "types": ["node"],
+    "allowJs": true,
+    "checkJs": false
+  },
+  "include": ["src/**/*", "types/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/types/index.d.ts

@@ -0,0 +1,189 @@
+import type { Plugin, BuildEnvironmentOptions, ViteDevServer } from 'vite';
+import type { RuntimePrimitives } from '@ripple-ts/adapter';
+
+// ============================================================================
+// Plugin exports
+// ============================================================================
+
+export interface OctanePluginOptions {
+	/** Override the client HMR default (on in serve mode, off for SSR). */
+	hmr?: boolean;
+}
+
+/**
+ * The octane metaframework plugin. Returns an array:
+ * `[octane(), metaPlugin]` — the first compiles `.tsrx`, the second owns
+ * config / routing / dev SSR / hydrate.
+ */
+export function octane(options?: OctanePluginOptions): Plugin[];
+export function defineConfig(options: OctaneConfigOptions): OctaneConfigOptions;
+export function resolveOctaneConfig(
+	raw: OctaneConfigOptions,
+	options?: { requireAdapter?: boolean },
+): ResolvedOctaneConfig;
+export function getOctaneConfigPath(projectRoot: string): string;
+export function octaneConfigExists(projectRoot: string): boolean;
+export function loadOctaneConfig(
+	projectRoot: string,
+	options?: { vite?: ViteDevServer; requireAdapter?: boolean },
+): Promise<ResolvedOctaneConfig>;
+
+// ============================================================================
+// Route classes
+// ============================================================================
+
+export class RenderRoute {
+	readonly type: 'render';
+	path: string;
+	entry: RenderRouteEntry;
+	layout?: string;
+	before: Middleware[];
+	constructor(options: RenderRouteOptions);
+}
+
+export class ServerRoute {
+	readonly type: 'server';
+	path: string;
+	methods: string[];
+	handler: RouteHandler;
+	before: Middleware[];
+	after: Middleware[];
+	constructor(options: ServerRouteOptions);
+}
+
+export type Route = RenderRoute | ServerRoute;
+
+// ============================================================================
+// Route options
+// ============================================================================
+
+export interface RenderRouteOptions {
+	/** URL path pattern (e.g., '/', '/posts/:id', '/docs/*slug') */
+	path: string;
+	/** Path to the component entry file, optionally with a preferred named export */
+	entry: RenderRouteEntry;
+	/** Path to the layout component (wraps the entry) */
+	layout?: string;
+	/** Middleware to run before rendering */
+	before?: Middleware[];
+}
+
+export interface ServerRouteOptions {
+	/** URL path pattern (e.g., '/api/hello', '/api/posts/:id') */
+	path: string;
+	/** HTTP methods to handle (default: ['GET']) */
+	methods?: string[];
+	/** Request handler that returns a Response */
+	handler: RouteHandler;
+	/** Middleware to run before the handler */
+	before?: Middleware[];
+	/** Middleware to run after the handler */
+	after?: Middleware[];
+}
+
+// ============================================================================
+// Context and middleware
+// ============================================================================
+
+export interface Context {
+	/** The incoming Request object */
+	request: Request;
+	/** URL parameters extracted from the route pattern */
+	params: Record<string, string>;
+	/** Parsed URL object */
+	url: URL;
+	/** Shared state for passing data between middlewares */
+	state: Map<string, unknown>;
+}
+
+export type NextFunction = () => Promise<Response>;
+export type Middleware = (context: Context, next: NextFunction) => Response | Promise<Response>;
+export type RouteHandler = (context: Context) => Response | Promise<Response>;
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+export type Component<T = Record<string, any>> = (
+	scope: any,
+	props: T,
+	extra?: any,
+) => string | void;
+
+export type RenderRouteEntry = string | readonly [exportName: string, path: string];
+
+export interface RootBoundaryOptions {
+	pending?: Component<Record<string, never>>;
+	catch?: Component<{ error: unknown; reset: () => void }>;
+}
+
+export interface OctaneConfigOptions {
+	build?: {
+		/** Output directory for the production build. @default 'dist' */
+		outDir?: string;
+		minify?: boolean;
+		target?: BuildEnvironmentOptions['target'];
+	};
+	adapter?: {
+		serve: AdapterServeFunction;
+		/**
+		 * Platform-specific runtime primitives provided by the adapter.
+		 * Required for production builds; in development the plugin falls back
+		 * to Node.js defaults if not provided.
+		 */
+		runtime: RuntimePrimitives;
+	};
+	router?: {
+		routes: Route[];
+	};
+	/** Global root pending/catch UI used by client and SSR render roots */
+	rootBoundary?: RootBoundaryOptions;
+	/** Global middlewares applied to all routes */
+	middlewares?: Middleware[];
+	platform?: {
+		env: Record<string, string>;
+	};
+	server?: {
+		/**
+		 * Trust `X-Forwarded-Proto` / `X-Forwarded-Host` when deriving the
+		 * request origin. Enable only behind a trusted reverse proxy.
+		 * @default false
+		 */
+		trustProxy?: boolean;
+	};
+}
+
+/**
+ * Resolved configuration with all defaults applied.
+ */
+export interface ResolvedOctaneConfig {
+	build: {
+		/** @default 'dist' */
+		outDir: string;
+		minify?: boolean;
+		target?: BuildEnvironmentOptions['target'];
+	};
+	adapter?: {
+		serve: AdapterServeFunction;
+		runtime: RuntimePrimitives;
+	};
+	router: {
+		routes: Route[];
+	};
+	rootBoundary: RootBoundaryOptions;
+	/** @default [] */
+	middlewares: Middleware[];
+	platform: {
+		/** @default {} */
+		env: Record<string, string>;
+	};
+	server: {
+		/** @default false */
+		trustProxy: boolean;
+	};
+}
+
+export type AdapterServeFunction = (
+	handler: (request: Request, platform?: unknown) => Response | Promise<Response>,
+	options?: Record<string, unknown>,
+) => { listen: (port?: number) => unknown; close: () => void };

package/types/production.d.ts

@@ -0,0 +1,59 @@
+import type { RuntimePrimitives } from '@ripple-ts/adapter';
+import type {
+	Route,
+	Middleware,
+	ResolvedOctaneConfig,
+	OctaneConfigOptions,
+	RootBoundaryOptions,
+} from '@octanejs/vite-plugin';
+
+export function resolveOctaneConfig(
+	raw: OctaneConfigOptions,
+	options?: { requireAdapter?: boolean },
+): ResolvedOctaneConfig;
+
+export interface ClientAssetEntry {
+	/** Path to the built JS file (relative to client output dir) */
+	js: string;
+	/** Paths to the built CSS files (relative to client output dir) */
+	css: string[];
+}
+
+export interface ServerManifest {
+	routes: Route[];
+	components: Record<string, Function>;
+	layouts: Record<string, Function>;
+	middlewares: Middleware[];
+	/** Map of entry path → _$_server_$_ object for RPC support */
+	rpcModules?: Record<string, Record<string, Function>>;
+	/** Trust X-Forwarded-* headers when deriving origin for RPC fetch */
+	trustProxy?: boolean;
+	rootBoundary?: RootBoundaryOptions;
+	/** Platform-specific runtime primitives from the adapter */
+	runtime: RuntimePrimitives;
+	/** Map of route entry paths to built client asset paths (preload tags). */
+	clientAssets?: Record<string, ClientAssetEntry>;
+}
+
+/**
+ * octane RenderResult — `render()` is async; `css` is ALREADY a ready,
+ * deduped `<style data-octane="hash">…</style>` string (NOT a Set<string>
+ * needing a `getCss` lookup like Ripple).
+ */
+export interface RenderResult {
+	head: string;
+	body: string;
+	css: string;
+}
+
+export interface HandlerOptions {
+	render: (component: Function, props?: unknown) => Promise<RenderResult>;
+	htmlTemplate: string;
+	executeServerFunction: (fn: Function, body: string) => Promise<string>;
+}
+
+/** Production fetch-handler factory. PHASE 2. */
+export function createHandler(
+	manifest: ServerManifest,
+	options: HandlerOptions,
+): (request: Request) => Promise<Response>;