blumenjs 0.2.4 → 0.2.6

package/dist/templates/app/shared/serverAction.ts

@@ -0,0 +1,84 @@
+/**
+ * Blumen Server Actions
+ *
+ * Define server-side functions that can be called directly from client
+ * components without writing API routes. Actions run on the server (Node)
+ * and are routed through Go.
+ *
+ * @example
+ * // app/actions/auth.ts
+ * import { action } from "@/shared/serverAction";
+ *
+ * export const loginAction = action("login", async (data: { email: string; password: string }) => {
+ *   const user = await db.users.findByEmail(data.email);
+ *   if (!user || !verifyPassword(data.password, user.hash)) {
+ *     return { success: false, error: "Invalid credentials" };
+ *   }
+ *   return { success: true, user: { id: user.id, name: user.name } };
+ * });
+ */
+
+// ── Types ──────────────────────────────────────────────────────
+
+export interface ActionResult<T = any> {
+	success: boolean;
+	data?: T;
+	error?: string;
+}
+
+export interface ActionDefinition<TInput = any, TOutput = any> {
+	/** Unique action name */
+	name: string;
+	/** The server-side handler */
+	handler: (input: TInput) => Promise<TOutput>;
+}
+
+// ── Server-Side: Action Registry ───────────────────────────────
+
+// Global registry of all defined actions (server-side only)
+const actionRegistry = new Map<string, (input: any) => Promise<any>>();
+
+/**
+ * Define a server action. This function registers the handler on the server
+ * and returns a callable reference for use with useServerAction on the client.
+ */
+export function action<TInput, TOutput>(
+	name: string,
+	handler: (input: TInput) => Promise<TOutput>,
+): ActionDefinition<TInput, TOutput> {
+	actionRegistry.set(name, handler);
+	return { name, handler };
+}
+
+/**
+ * Execute a registered action by name (called by the Node SSR server).
+ */
+export async function executeAction(
+	name: string,
+	input: any,
+): Promise<ActionResult> {
+	const handler = actionRegistry.get(name);
+	if (!handler) {
+		return { success: false, error: `Action "${name}" not found` };
+	}
+
+	try {
+		const result = await handler(input);
+		return { success: true, data: result };
+	} catch (err: any) {
+		return {
+			success: false,
+			error:
+				process.env.NODE_ENV === "development"
+					? err.message || String(err)
+					: "Server action failed",
+		};
+	}
+}
+
+/**
+ * Get all registered action names (for debugging/monitoring).
+ */
+export function getRegisteredActions(): string[] {
+	return Array.from(actionRegistry.keys());
+}

package/dist/templates/app/shared/types.ts

@@ -0,0 +1,132 @@
+/**
+ * Blumen Framework Types
+ *
+ * Shared type definitions for the BlumenJS framework.
+ * These types are used by both page components and the SSR engine.
+ */
+
+/**
+ * Context object passed to getServerProps.
+ * Contains everything the server knows about the incoming request.
+ */
+export interface BlumenContext {
+	/** Dynamic route parameters (e.g. { id: "42" } for /users/[id]) */
+	params: Record<string, string>;
+	/** URL query string parameters */
+	query: Record<string, string[]>;
+	/** The request URL path (e.g. "/users/42") */
+	path: string;
+	/** A subset of request headers (forwarded from Go) */
+	headers?: Record<string, string>;
+}
+
+/**
+ * Return type for getServerProps.
+ * Must return an object with a `props` key containing the page props.
+ * Optionally include `revalidate` to enable page caching (in seconds).
+ */
+export interface ServerPropsResult {
+	props: Record<string, any>;
+	/** Cache TTL in seconds. The page will be cached and served from Go memory.
+	 *  After this time, stale content is served while Go revalidates in the background.
+	 *  Set to 0 or omit to disable caching for this page. */
+	revalidate?: number;
+}
+
+/**
+ * The getServerProps function signature.
+ *
+ * Export this from any page component to fetch data on the server
+ * before the page is rendered. The returned props are merged into
+ * the page component's props.
+ *
+ * @example
+ * ```tsx
+ * // app/pages/users/[id].tsx
+ * import type { BlumenContext, ServerPropsResult } from '../../shared/types';
+ *
+ * export async function getServerProps(ctx: BlumenContext): Promise<ServerPropsResult> {
+ *     const user = await fetch(`https://api.example.com/users/${ctx.params.id}`);
+ *     return { props: { user: await user.json() } };
+ * }
+ *
+ * export default function UserPage({ user }) {
+ *     return <h1>{user.name}</h1>;
+ * }
+ * ```
+ */
+export type GetServerProps = (
+	ctx: BlumenContext,
+) => Promise<ServerPropsResult> | ServerPropsResult;
+
+/**
+ * Metadata object for per-page SEO and `<head>` tag management.
+ *
+ * Export a `metadata` constant from any page to set static head tags,
+ * or export a `generateMetadata(ctx)` function for dynamic metadata
+ * based on route params, query strings, or fetched data.
+ *
+ * @example
+ * ```tsx
+ * // Static metadata
+ * export const metadata: BlumenMetadata = {
+ *     title: 'About Us | My App',
+ *     description: 'Learn about our team and mission.',
+ *     openGraph: { image: '/static/og-about.jpg' },
+ * };
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Dynamic metadata
+ * export function generateMetadata(ctx: BlumenContext): BlumenMetadata {
+ *     return {
+ *         title: `User ${ctx.params.id} | My App`,
+ *         description: `Profile page for user ${ctx.params.id}`,
+ *     };
+ * }
+ * ```
+ */
+export interface BlumenMetadata {
+	/** Page title — rendered as `<title>` */
+	title?: string;
+	/** Page description — `<meta name="description">` */
+	description?: string;
+	/** Keywords — `<meta name="keywords">` */
+	keywords?: string[];
+	/** Robots directive — `<meta name="robots">` (e.g. "noindex, nofollow") */
+	robots?: string;
+	/** Canonical URL — `<link rel="canonical">` */
+	canonical?: string;
+	/** Open Graph metadata for social sharing (Facebook, LinkedIn, etc.) */
+	openGraph?: {
+		title?: string;
+		description?: string;
+		image?: string;
+		url?: string;
+		type?: string;
+		siteName?: string;
+	};
+	/** Twitter Card metadata */
+	twitter?: {
+		card?: "summary" | "summary_large_image" | "app" | "player";
+		title?: string;
+		description?: string;
+		image?: string;
+		creator?: string;
+		site?: string;
+	};
+	/** Escape hatch: arbitrary `<meta name="key" content="value">` tags */
+	other?: Record<string, string>;
+}
+
+/**
+ * Function signature for dynamic metadata generation.
+ *
+ * Export this from a page to generate metadata based on the request context.
+ * Receives the same `BlumenContext` as `getServerProps`.
+ */
+export type GenerateMetadata = (
+	ctx: BlumenContext,
+) => Promise<BlumenMetadata> | BlumenMetadata;
+

package/dist/templates/app/shared/useServerAction.ts

@@ -0,0 +1,173 @@
+/**
+ * Blumen useServerAction Hook
+ *
+ * Call server actions directly from React components without writing
+ * API routes. Actions run on the server and return typed results.
+ *
+ * Includes built-in CSRF protection via double-submit cookie pattern.
+ *
+ * @example
+ * import { useServerAction } from "@/shared/useServerAction";
+ *
+ * function LoginForm() {
+ *   const { execute, isPending, error, data } = useServerAction("login");
+ *
+ *   const handleSubmit = async (e: React.FormEvent) => {
+ *     e.preventDefault();
+ *     const result = await execute({ email, password });
+ *     if (result.success) router.push("/dashboard");
+ *   };
+ *
+ *   return (
+ *     <form onSubmit={handleSubmit}>
+ *       <input name="email" />
+ *       <input name="password" type="password" />
+ *       <button disabled={isPending}>
+ *         {isPending ? "Logging in..." : "Login"}
+ *       </button>
+ *       {error && <p>{error}</p>}
+ *     </form>
+ *   );
+ * }
+ */
+
+import { useState, useCallback, useRef, useEffect } from "react";
+
+// ── Types ──────────────────────────────────────────────────────
+
+export interface ActionResult<T = any> {
+	success: boolean;
+	data?: T;
+	error?: string;
+}
+
+export interface UseServerActionOptions {
+	/** Called on successful execution */
+	onSuccess?: (data: any) => void;
+	/** Called on error */
+	onError?: (error: string) => void;
+}
+
+export interface UseServerActionReturn<TInput = any, TOutput = any> {
+	/** Execute the server action */
+	execute: (input?: TInput) => Promise<ActionResult<TOutput>>;
+	/** Whether the action is currently executing */
+	isPending: boolean;
+	/** The last error message */
+	error: string | null;
+	/** The last successful result data */
+	data: TOutput | null;
+	/** Reset the state */
+	reset: () => void;
+}
+
+// ── CSRF Token ─────────────────────────────────────────────────
+
+let csrfToken: string | null = null;
+
+function getCSRFToken(): string {
+	if (csrfToken) return csrfToken;
+
+	// Generate a random CSRF token
+	if (typeof window !== "undefined" && window.crypto) {
+		const array = new Uint8Array(32);
+		window.crypto.getRandomValues(array);
+		csrfToken = Array.from(array, (b) => b.toString(16).padStart(2, "0")).join(
+			"",
+		);
+	} else {
+		csrfToken = Math.random().toString(36).slice(2) + Date.now().toString(36);
+	}
+
+	// Set as a cookie so the server can validate (double-submit pattern)
+	if (typeof document !== "undefined") {
+		document.cookie = `_blumen_csrf=${csrfToken}; path=/; SameSite=Strict`;
+	}
+
+	return csrfToken;
+}
+
+// ── Hook ───────────────────────────────────────────────────────
+
+export function useServerAction<TInput = any, TOutput = any>(
+	actionName: string,
+	options: UseServerActionOptions = {},
+): UseServerActionReturn<TInput, TOutput> {
+	const { onSuccess, onError } = options;
+
+	const [isPending, setIsPending] = useState(false);
+	const [error, setError] = useState<string | null>(null);
+	const [data, setData] = useState<TOutput | null>(null);
+	const mountedRef = useRef(true);
+
+	useEffect(() => {
+		mountedRef.current = true;
+		return () => {
+			mountedRef.current = false;
+		};
+	}, []);
+
+	const execute = useCallback(
+		async (input?: TInput): Promise<ActionResult<TOutput>> => {
+			setIsPending(true);
+			setError(null);
+
+			try {
+				const token = getCSRFToken();
+
+				const response = await fetch("/_blumen/action", {
+					method: "POST",
+					headers: {
+						"Content-Type": "application/json",
+						"X-CSRF-Token": token,
+					},
+					body: JSON.stringify({
+						action: actionName,
+						input: input || {},
+					}),
+					credentials: "same-origin",
+				});
+
+				if (!response.ok) {
+					const errText = await response.text();
+					throw new Error(errText || `Action failed: ${response.status}`);
+				}
+
+				const result: ActionResult<TOutput> = await response.json();
+
+				if (mountedRef.current) {
+					if (result.success) {
+						setData(result.data || null);
+						setError(null);
+						onSuccess?.(result.data);
+					} else {
+						setError(result.error || "Action failed");
+						onError?.(result.error || "Action failed");
+					}
+					setIsPending(false);
+				}
+
+				return result;
+			} catch (err: any) {
+				const errorMsg = err.message || "Network error";
+				if (mountedRef.current) {
+					setError(errorMsg);
+					setIsPending(false);
+					onError?.(errorMsg);
+				}
+				return { success: false, error: errorMsg };
+			}
+		},
+		[actionName, onSuccess, onError],
+	);
+
+	const reset = useCallback(() => {
+		setIsPending(false);
+		setError(null);
+		setData(null);
+	}, []);
+
+	return { execute, isPending, error, data, reset };
+}
+
+export default useServerAction;

package/dist/templates/app/shared/useWebSocket.ts

@@ -0,0 +1,237 @@
+/**
+ * Blumen useWebSocket Hook
+ *
+ * Connects to the Go-powered WebSocket server at /_blumen/ws.
+ * Provides send/receive functions, room management, and auto-reconnect.
+ *
+ * Go handles each connection in a goroutine — 100K+ concurrent connections
+ * with minimal memory. This is Blumen's real-time superpower.
+ *
+ * @example
+ * const { send, lastMessage, isConnected } = useWebSocket();
+ * send({ type: "chat", payload: { text: "Hello!" } });
+ */
+
+import { useState, useEffect, useRef, useCallback } from "react";
+
+// ── Types ──────────────────────────────────────────────────────
+
+export interface WSMessage {
+	type: string;
+	room?: string;
+	payload?: any;
+	sender?: string;
+}
+
+export interface UseWebSocketOptions {
+	/** Auto-connect on mount. Defaults to true. */
+	autoConnect?: boolean;
+	/** Auto-reconnect on disconnect. Defaults to true. */
+	reconnect?: boolean;
+	/** Reconnect delay in ms. Defaults to 1000. */
+	reconnectDelay?: number;
+	/** Max reconnect attempts. Defaults to 10. */
+	maxReconnectAttempts?: number;
+	/** Filter messages by type. Only messages matching these types are stored in lastMessage. */
+	messageTypes?: string[];
+	/** Custom WebSocket URL. Defaults to ws://hostname/_blumen/ws */
+	url?: string;
+	/** Called when connection opens */
+	onOpen?: () => void;
+	/** Called when a message is received */
+	onMessage?: (msg: WSMessage) => void;
+	/** Called when connection closes */
+	onClose?: (event: CloseEvent) => void;
+	/** Called on error */
+	onError?: (event: Event) => void;
+}
+
+export interface UseWebSocketReturn {
+	/** Send a message to the server */
+	send: (msg: Omit<WSMessage, "sender">) => void;
+	/** Send raw JSON */
+	sendJSON: (data: any) => void;
+	/** The last received message */
+	lastMessage: WSMessage | null;
+	/** All received messages (capped at 100) */
+	messages: WSMessage[];
+	/** Whether the socket is connected */
+	isConnected: boolean;
+	/** The client's unique ID (assigned by the server) */
+	clientId: string | null;
+	/** Join a room for scoped messaging */
+	joinRoom: (room: string) => void;
+	/** Leave a room */
+	leaveRoom: (room: string) => void;
+	/** Manually connect */
+	connect: () => void;
+	/** Manually disconnect */
+	disconnect: () => void;
+}
+
+const MAX_MESSAGES = 100;
+
+// ── Hook ───────────────────────────────────────────────────────
+
+export function useWebSocket(options: UseWebSocketOptions = {}): UseWebSocketReturn {
+	const {
+		autoConnect = true,
+		reconnect = true,
+		reconnectDelay = 1000,
+		maxReconnectAttempts = 10,
+		messageTypes,
+		url,
+		onOpen,
+		onMessage,
+		onClose,
+		onError,
+	} = options;
+
+	const [isConnected, setIsConnected] = useState(false);
+	const [lastMessage, setLastMessage] = useState<WSMessage | null>(null);
+	const [messages, setMessages] = useState<WSMessage[]>([]);
+	const [clientId, setClientId] = useState<string | null>(null);
+
+	const wsRef = useRef<WebSocket | null>(null);
+	const reconnectAttemptsRef = useRef(0);
+	const reconnectTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+	const mountedRef = useRef(true);
+
+	// Build the WebSocket URL
+	const getUrl = useCallback(() => {
+		if (url) return url;
+		if (typeof window === "undefined") return "";
+		const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
+		return `${protocol}//${window.location.host}/_blumen/ws`;
+	}, [url]);
+
+	// ── Connect ────────────────────────────────────────────────
+	const connect = useCallback(() => {
+		if (wsRef.current?.readyState === WebSocket.OPEN) return;
+
+		const wsUrl = getUrl();
+		if (!wsUrl) return;
+
+		const ws = new WebSocket(wsUrl);
+		wsRef.current = ws;
+
+		ws.onopen = () => {
+			if (!mountedRef.current) return;
+			setIsConnected(true);
+			reconnectAttemptsRef.current = 0;
+			onOpen?.();
+		};
+
+		ws.onmessage = (event) => {
+			if (!mountedRef.current) return;
+
+			try {
+				const msg: WSMessage = JSON.parse(event.data);
+
+				// Handle the server's "connected" message to store client ID
+				if (msg.type === "connected" && typeof msg.payload === "string") {
+					setClientId(msg.payload);
+					return;
+				}
+
+				// Filter by message types if specified
+				if (messageTypes && !messageTypes.includes(msg.type)) {
+					// Still call the onMessage callback even if filtered
+					onMessage?.(msg);
+					return;
+				}
+
+				setLastMessage(msg);
+				setMessages((prev) => {
+					const next = [...prev, msg];
+					return next.length > MAX_MESSAGES ? next.slice(-MAX_MESSAGES) : next;
+				});
+
+				onMessage?.(msg);
+			} catch {
+				// Not JSON — ignore
+			}
+		};
+
+		ws.onclose = (event) => {
+			if (!mountedRef.current) return;
+			setIsConnected(false);
+			onClose?.(event);
+
+			// Auto-reconnect
+			if (reconnect && reconnectAttemptsRef.current < maxReconnectAttempts) {
+				const delay = reconnectDelay * Math.pow(1.5, reconnectAttemptsRef.current);
+				reconnectAttemptsRef.current++;
+				reconnectTimerRef.current = setTimeout(() => {
+					if (mountedRef.current) connect();
+				}, delay);
+			}
+		};
+
+		ws.onerror = (event) => {
+			onError?.(event);
+		};
+	}, [getUrl, onOpen, onMessage, onClose, onError, reconnect, reconnectDelay, maxReconnectAttempts, messageTypes]);
+
+	// ── Disconnect ─────────────────────────────────────────────
+	const disconnect = useCallback(() => {
+		if (reconnectTimerRef.current) {
+			clearTimeout(reconnectTimerRef.current);
+		}
+		reconnectAttemptsRef.current = maxReconnectAttempts; // Prevent auto-reconnect
+		wsRef.current?.close(1000, "Client disconnect");
+		wsRef.current = null;
+		setIsConnected(false);
+	}, [maxReconnectAttempts]);
+
+	// ── Send ───────────────────────────────────────────────────
+	const send = useCallback((msg: Omit<WSMessage, "sender">) => {
+		if (wsRef.current?.readyState === WebSocket.OPEN) {
+			wsRef.current.send(JSON.stringify(msg));
+		}
+	}, []);
+
+	const sendJSON = useCallback((data: any) => {
+		if (wsRef.current?.readyState === WebSocket.OPEN) {
+			wsRef.current.send(JSON.stringify(data));
+		}
+	}, []);
+
+	// ── Room Management ────────────────────────────────────────
+	const joinRoom = useCallback((room: string) => {
+		send({ type: "join", payload: room });
+	}, [send]);
+
+	const leaveRoom = useCallback((room: string) => {
+		send({ type: "leave", payload: room });
+	}, [send]);
+
+	// ── Lifecycle ──────────────────────────────────────────────
+	useEffect(() => {
+		mountedRef.current = true;
+		if (autoConnect) connect();
+
+		return () => {
+			mountedRef.current = false;
+			if (reconnectTimerRef.current) {
+				clearTimeout(reconnectTimerRef.current);
+			}
+			wsRef.current?.close(1000, "Component unmount");
+		};
+	}, [autoConnect, connect]);
+
+	return {
+		send,
+		sendJSON,
+		lastMessage,
+		messages,
+		isConnected,
+		clientId,
+		joinRoom,
+		leaveRoom,
+		connect,
+		disconnect,
+	};
+}
+
+export default useWebSocket;

package/dist/templates/go.mod

@@ -0,0 +1,8 @@
+module blumenjs/go-server
+
+go 1.25.4
+
+require (
+	github.com/gorilla/websocket v1.5.3 // indirect
+	golang.org/x/image v0.40.0 // indirect
+)

package/dist/templates/go.sum

@@ -0,0 +1,4 @@
+github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
+github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+golang.org/x/image v0.40.0 h1:Tw4GyDXMo+daZN1znreBRC3VayR1aLFUyUEOLUdW1a8=
+golang.org/x/image v0.40.0/go.mod h1:uIc348UZMSvS5Z65CVZ7iDPaNobNFEPeJ4kbqTOszmA=