@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/app/modules/app-def/index.ts

@@ -0,0 +1,225 @@
+/**
+ * `defineApp` + `serve` + `hydrate` — the single-config entry point:
+ *
+ *   // solid.config.ts
+ *   export default defineApp({
+ *     render: () => <App />,
+ *     config: { render: { "/": "stream" } },
+ *     server: { ops: { metrics: true }, ai: { mcp: { token } } },
+ *   });
+ *
+ *   // src/entry-server.tsx
+ *   export default serve(app);            // virtual modules wired in
+ *   // src/entry-client.tsx
+ *   hydrate(app);                         // preload matched + hydrate
+ */
+
+import type { JSX } from "solid-js";
+import type { SolidFrameworkConfig } from "#app/types";
+import { resolveConfig } from "../config";
+import type { UserConfig } from "../config/domain/models/config";
+import {
+	type AnyEnvField,
+	type CreateEnvOptions,
+	createEnv,
+} from "../env/domain/operations/create-env";
+import { createAppServer } from "../server-entry";
+
+const APP_DEF = "__sfApp";
+
+export interface AppDef<
+	S extends Record<string, AnyEnvField<unknown>> = Record<
+		string,
+		AnyEnvField<unknown>
+	>,
+	P extends Record<string, AnyEnvField<unknown>> = Record<
+		string,
+		AnyEnvField<unknown>
+	>,
+> {
+	[APP_DEF]: true;
+	/** App name — surfaces in ops payloads (/_health) and MCP */
+	name?: string;
+	/** Root component — both entries render this */
+	render: () => JSX.Element;
+	/** Framework config (rules, head, zones, i18n, pwa, sitemap) */
+	config?: UserConfig;
+	/**
+	 * Typed env — `{ server: {...}, public: {...} }` validated at boot;
+	 * read it via `useEnv()` (server vars throw on the client)
+	 */
+	env?: CreateEnvOptions<S, P>;
+	/**
+	 * Plugins — merge `config`/`server` fragments into the app;
+	 * app-level options always win over plugin defaults
+	 */
+	plugins?: AppPlugin[];
+	/** Server options — ops, ai, seo, og, apiDocs, islands, devtools */
+	server?: Omit<
+		Parameters<typeof createAppServer>[0],
+		"app" | "config" | "fileRoutes"
+	>;
+}
+
+export interface AppPlugin {
+	/** Merged under app.config — route rules, head, zones, etc */
+	config?: UserConfig;
+	/** Merged under app.server — ops flags, islands, devtools */
+	server?: Omit<
+		Parameters<typeof createAppServer>[0],
+		"app" | "config" | "fileRoutes"
+	>;
+}
+
+type ParsedEnv<
+	S extends Record<string, AnyEnvField<unknown>>,
+	P extends Record<string, AnyEnvField<unknown>>,
+> = ReturnType<typeof createEnv<S, P>>;
+
+// Latest defineApp env — solid.config.tsx is imported by both
+// entries so the parsed bag is shared app-wide
+let currentEnv: unknown;
+
+/**
+ * `useEnv<T>()` — typed env bag from `defineApp({ env })`;
+ * server keys throw when read on the client
+ */
+export const useEnv = <T = Record<string, unknown>>(): T => currentEnv as T;
+
+/**
+ * `setEnv(obj)` — dev-time override of the env bag (e.g. feature
+ * toggles without a restart). Not for production secrets.
+ */
+export const setEnv = (env: unknown): void => {
+	currentEnv = env;
+};
+
+export const defineApp = <
+	S extends Record<string, AnyEnvField<unknown>> = Record<
+		string,
+		AnyEnvField<unknown>
+	>,
+	P extends Record<string, AnyEnvField<unknown>> = Record<
+		string,
+		AnyEnvField<unknown>
+	>,
+>(
+	def: Omit<AppDef<S, P>, typeof APP_DEF | "env"> & {
+		env?: CreateEnvOptions<S, P>;
+	},
+): AppDef<S, P> & { env?: ParsedEnv<S, P> } => {
+	const parsed = def.env ? createEnv(def.env) : undefined;
+	if (parsed !== undefined) currentEnv = parsed;
+	return { [APP_DEF]: true, ...def, env: parsed } as AppDef<S, P> & {
+		env?: ParsedEnv<S, P>;
+	};
+};
+
+export const isAppDef = (v: unknown): v is AppDef =>
+	typeof v === "object" &&
+	v !== null &&
+	(v as Record<string, unknown>)[APP_DEF] === true;
+
+interface VirtualRoutes {
+	manifest?: unknown;
+	routeModules?: unknown;
+	preloadRoute?: (path: string) => Promise<unknown>;
+}
+
+// Literal specifiers — vite resolves the virtual ids when serve()/
+// hydrate() is bundled into an app that uses the plugin; plain runtimes
+// fall through to the catch → empty modules → config fallback
+const virtualRoutes = async (): Promise<VirtualRoutes> => {
+	try {
+		return (await import("virtual:solid-framework/routes")) as VirtualRoutes;
+	} catch {
+		return {};
+	}
+};
+const virtualConfig = async (): Promise<{ default?: SolidFrameworkConfig }> => {
+	try {
+		return (await import("virtual:solid-framework/config")) as {
+			default?: SolidFrameworkConfig;
+		};
+	} catch {
+		return {};
+	}
+};
+const virtualServerFns = async (): Promise<void> => {
+	try {
+		await import("virtual:solid-framework/server-fns");
+	} catch {
+		// no server fns registered
+	}
+};
+
+/**
+ * serve(app) — fetch handler for entry-server.tsx.
+ * Wires the vite virtual manifest/server-fns/config into createAppServer;
+ * falls back to `app.config` when no virtual config exists (plain bun).
+ */
+export const serve = (
+	app: AppDef,
+	/** Per-entry overrides merged over `app.server` (e.g. trustProxy) */
+	options?: AppDef["server"],
+): ((request: Request) => Promise<Response>) => {
+	let inner: Promise<(request: Request) => Promise<Response>> | undefined;
+	return async (request) => {
+		inner ??= (async () => {
+			const routes = await virtualRoutes();
+			void virtualServerFns();
+			const vconfig = await virtualConfig();
+			// instrumentation.ts auto-discovery is baked into the generated
+			// virtual config — app.config must not clobber it
+			const pluginConfig = {} as UserConfig;
+			const pluginServer = {} as NonNullable<AppDef["server"]>;
+			for (const p of app.plugins ?? []) {
+				Object.assign(pluginConfig, p.config ?? {});
+				Object.assign(pluginServer, p.server ?? {});
+			}
+			const merged = { ...pluginConfig, ...(app.config ?? {}) };
+			const config = app.config
+				? {
+						...resolveConfig(merged),
+						instrumentation:
+							app.config.instrumentation ?? vconfig.default?.instrumentation,
+					}
+				: app.plugins?.length
+					? resolveConfig(merged)
+					: (vconfig.default ?? resolveConfig({}));
+			const fileRoutes =
+				routes.manifest && routes.routeModules
+					? {
+							manifest: routes.manifest as never,
+							modules: routes.routeModules as never,
+						}
+					: undefined;
+			if (!fileRoutes) {
+				console.warn(
+					"[solid-framework] serve(): no virtual:solid-framework/routes — running outside vite; file routes disabled",
+				);
+			}
+			return createAppServer({
+				app: app.render,
+				config,
+				fileRoutes,
+				...pluginServer,
+				...(app.server ?? {}),
+				...(options ?? {}),
+			});
+		})();
+		return (await inner)(request);
+	};
+};
+
+/**
+ * hydrate(app) — entry-client.tsx. Preloads the matched route module
+ * (so routeComponent resolves synchronously → clean hydration) then
+ * mounts the app under the same provider stack as the server.
+ */
+export const hydrate = async (app: AppDef): Promise<void> => {
+	const routes = await virtualRoutes();
+	await routes.preloadRoute?.(window.location.pathname);
+	const { createClientEntry } = await import("#render/presentation/entries");
+	createClientEntry(app.render);
+};

package/src/app/modules/auth/application/usecases/auth.ts

@@ -0,0 +1,161 @@
+/**
+ * Auth Kit
+ * Thin orchestration over the signed-cookie session primitives —
+ * middleware resolves the user into route state, useUser() reads it
+ * on server and client, requireUser() guards loaders/actions:
+ *
+ *   const auth = createAuth({
+ *     secret: env.AUTH_SECRET,
+ *     resolve: async (data) => db.users.find(data.id) ?? null,
+ *   });
+ *
+ *   // config
+ *   middleware: [auth.middleware]
+ *
+ *   // route
+ *   export const beforeLoad = auth.requireUser("/login");
+ *   export const loader = async (ctx) => auth.user(ctx.request);
+ */
+
+import { useRouteState } from "#app/modules/file-routes/presentation/location";
+import type { AppMiddleware } from "#app/types";
+import {
+	type CookieOptions,
+	createSession,
+	type Session,
+} from "#server/modules/http/domain/operations/cookies";
+
+export interface AuthOptions<TUser = unknown, TSession = unknown> {
+	/** Signing secret for the session cookie */
+	secret: string;
+	/** Cookie name — default "sf_session" */
+	cookieName?: string;
+	cookie?: CookieOptions;
+	/**
+	 * Session store — default is the signed cookie; pass
+	 * `memorySessionStore()`/`kvSessionStore(kv)` for server-side sessions
+	 */
+	store?: Session<TSession>;
+	/** Map session data to a user object — default: session data as-is */
+	resolve?: (
+		data: TSession,
+		request: Request,
+	) => TUser | null | Promise<TUser | null>;
+	/**
+	 * Extract roles from a user — default reads `user.roles` (array)
+	 * or `user.role` (string)
+	 */
+	roles?: (user: TUser) => readonly string[];
+}
+
+export interface Auth<TUser = unknown, TSession = unknown> {
+	/** Request middleware — resolves session → state.user / state.session */
+	middleware: AppMiddleware;
+	/** Session data for the request — loaders/actions call directly */
+	session: (request: Request) => Promise<TSession | null>;
+	/** Resolved user for the request */
+	user: (request: Request) => Promise<TUser | null>;
+	/** beforeLoad-compatible guard — redirects when unauthenticated */
+	requireUser: (
+		redirectTo?: string,
+	) => (ctx: { request: Request }) => Promise<Response | undefined>;
+	/**
+	 * beforeLoad-compatible role guard — unauthenticated redirects to
+	 * `redirectTo`; authenticated without the role gets 403
+	 */
+	requireRole: (
+		role: string | readonly string[],
+		redirectTo?: string,
+	) => (ctx: { request: Request }) => Promise<Response | undefined>;
+	/** Write the session cookie (call inside a sign-in action) */
+	signIn: (headers: Headers, data: TSession) => Promise<void>;
+	/** Destroy the session cookie */
+	signOut: (headers: Headers) => void;
+	/** The underlying signed session */
+	store: Session<TSession>;
+}
+
+export const createAuth = <TUser = unknown, TSession = unknown>(
+	options: AuthOptions<TUser, TSession>,
+): Auth<TUser, TSession> => {
+	const store =
+		options.store ??
+		createSession<TSession>(options.secret, {
+			name: options.cookieName,
+			cookie: options.cookie,
+		});
+	const resolveUser = async (
+		request: Request,
+	): Promise<{ data: TSession | null; user: TUser | null }> => {
+		const data = await store.get(request);
+		if (data === null) return { data: null, user: null };
+		const user = options.resolve
+			? await options.resolve(data, request)
+			: (data as unknown as TUser);
+		return { data, user };
+	};
+
+	return {
+		middleware: async (ctx) => {
+			const { data, user } = await resolveUser(ctx.request);
+			ctx.state.session = data;
+			ctx.state.user = user;
+			return undefined;
+		},
+		session: (request) => store.get(request),
+		user: async (request) => (await resolveUser(request)).user,
+		requireUser:
+			(redirectTo = "/login") =>
+			async (ctx) => {
+				const { user } = await resolveUser(ctx.request);
+				if (user === null) {
+					const url = new URL(ctx.request.url);
+					return new Response(null, {
+						status: 302,
+						headers: {
+							Location: `${redirectTo}?next=${encodeURIComponent(url.pathname)}`,
+						},
+					});
+				}
+				return undefined;
+			},
+		requireRole:
+			(role, redirectTo = "/login") =>
+			async (ctx) => {
+				const { user } = await resolveUser(ctx.request);
+				if (user === null) {
+					const url = new URL(ctx.request.url);
+					return new Response(null, {
+						status: 302,
+						headers: {
+							Location: `${redirectTo}?next=${encodeURIComponent(url.pathname)}`,
+						},
+					});
+				}
+				const want = Array.isArray(role) ? role : [role];
+				const have = options.roles
+					? options.roles(user)
+					: (((user as { roles?: readonly string[] }).roles ??
+							[(user as { role?: string }).role].filter(
+								Boolean,
+							)) as readonly string[]);
+				if (!want.some((r) => have.includes(r))) {
+					return Response.json(
+						{ error: { code: "FORBIDDEN", message: "Insufficient role" } },
+						{ status: 403 },
+					);
+				}
+				return undefined;
+			},
+		signIn: (headers, data) => store.set(headers, data),
+		signOut: (headers) => store.destroy(headers),
+		store,
+	};
+};
+
+/**
+ * Current user inside components — reads route state on the server
+ * and the serialized payload after hydration
+ */
+export const useUser = <TUser = unknown>(): TUser | null =>
+	(useRouteState<{ user?: TUser | null }>().user ?? null) as TUser | null;

package/src/app/modules/auth/application/usecases/oauth.ts

@@ -0,0 +1,105 @@
+/**
+ * OAuth2 Provider Helper
+ * Generic authorization-code flow — pair with createAuth:
+ *
+ *   const github = createOAuthProvider({
+ *     authorizationUrl: "https://github.com/login/oauth/authorize",
+ *     tokenUrl: "https://github.com/login/oauth/access_token",
+ *     clientId: env.GH_ID,
+ *     clientSecret: env.GH_SECRET,
+ *   });
+ *
+ *   // GET /auth/github → redirect to provider
+ *   Response.redirect(github.authorize(redirectUri, state), 302);
+ *   // GET /auth/github/callback → exchange code → signIn
+ *   const tokens = await github.exchange(code, redirectUri);
+ */
+
+export interface OAuthProviderOptions {
+	authorizationUrl: string;
+	tokenUrl: string;
+	clientId: string;
+	clientSecret: string;
+	scope?: string;
+	/** Extra params on the authorize url (e.g. access_type, prompt) */
+	authorizeParams?: Record<string, string>;
+}
+
+export interface OAuthTokens {
+	access_token: string;
+	token_type?: string;
+	expires_in?: number;
+	refresh_token?: string;
+	scope?: string;
+	[key: string]: unknown;
+}
+
+export interface OAuthProvider {
+	/** Provider authorization URL for the browser redirect */
+	authorize: (redirectUri: string, state: string) => string;
+	/** Exchange the callback code for tokens */
+	exchange: (
+		code: string,
+		redirectUri: string,
+		fetchFn?: typeof fetch,
+	) => Promise<OAuthTokens>;
+	/** Provider-authenticated GET (userinfo endpoint, api calls) */
+	get: <T = unknown>(
+		url: string,
+		token: string,
+		fetchFn?: typeof fetch,
+	) => Promise<T>;
+}
+
+export const createOAuthProvider = (
+	options: OAuthProviderOptions,
+): OAuthProvider => ({
+	authorize: (redirectUri, state) => {
+		const url = new URL(options.authorizationUrl);
+		url.searchParams.set("response_type", "code");
+		url.searchParams.set("client_id", options.clientId);
+		url.searchParams.set("redirect_uri", redirectUri);
+		url.searchParams.set("state", state);
+		if (options.scope) url.searchParams.set("scope", options.scope);
+		for (const [k, v] of Object.entries(options.authorizeParams ?? {})) {
+			url.searchParams.set(k, v);
+		}
+		return url.toString();
+	},
+	exchange: async (code, redirectUri, fetchFn = fetch) => {
+		const response = await fetchFn(options.tokenUrl, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/x-www-form-urlencoded",
+				Accept: "application/json",
+			},
+			body: new URLSearchParams({
+				grant_type: "authorization_code",
+				code,
+				redirect_uri: redirectUri,
+				client_id: options.clientId,
+				client_secret: options.clientSecret,
+			}),
+		});
+		if (!response.ok) {
+			throw new Error(
+				`[solid-framework] oauth exchange failed: ${response.status}`,
+			);
+		}
+		return (await response.json()) as OAuthTokens;
+	},
+	get: async (url, token, fetchFn = fetch) => {
+		const response = await fetchFn(url, {
+			headers: {
+				Authorization: `Bearer ${token}`,
+				Accept: "application/json",
+			},
+		});
+		if (!response.ok) {
+			throw new Error(
+				`[solid-framework] oauth request failed: ${response.status}`,
+			);
+		}
+		return response.json();
+	},
+});

package/src/app/modules/auth/index.ts

@@ -0,0 +1,2 @@
+export * from "./application/usecases/auth";
+export * from "./application/usecases/oauth";

package/src/app/modules/cache/adapters/edge-kv.ts

@@ -0,0 +1,55 @@
+/**
+ * Edge KV Cache Adapter
+ * CacheStore over a KVNamespace-like binding (Cloudflare Workers KV,
+ * Deno KV via get/set, or any async KV). KV reads are async, so the
+ * adapter keeps a synchronous read-through shadow: misses trigger a
+ * background fetch that populates the shadow for the next request.
+ */
+
+import type { CacheStore } from "../ports/store";
+
+export interface KvBinding {
+	get(key: string): Promise<string | null>;
+	put(
+		key: string,
+		value: string,
+		options?: { expirationTtl?: number },
+	): Promise<void>;
+	delete(key: string): Promise<void>;
+	list(options?: { prefix?: string }): Promise<{ keys: { name: string }[] }>;
+}
+
+export const createEdgeKvStore = <V>(binding: KvBinding): CacheStore<V> => {
+	// Synchronous read-through shadow — edge runtimes are single
+	// request-scoped, so a stale shadow only costs one async miss
+	const shadow = new Map<string, V>();
+
+	const hydrate = (key: string): void => {
+		void binding.get(key).then((raw) => {
+			if (raw !== null) shadow.set(key, JSON.parse(raw) as V);
+		});
+	};
+
+	return {
+		get(key) {
+			const hit = shadow.get(key);
+			if (hit === undefined) hydrate(key);
+			return hit;
+		},
+		set(key, value) {
+			shadow.set(key, value);
+			void binding.put(key, JSON.stringify(value));
+		},
+		delete(key) {
+			shadow.delete(key);
+			void binding.delete(key);
+			return true;
+		},
+		keys() {
+			return [...shadow.keys()];
+		},
+		clear() {
+			shadow.clear();
+		},
+	};
+};

package/src/app/modules/cache/adapters/fs.ts

@@ -0,0 +1,58 @@
+/**
+ * Filesystem Cache Store
+ * Persists prerendered pages across restarts — entries land as JSON
+ * files under the cache dir. Sync fs keeps the cache surface
+ * synchronous; suitable for build servers and single-node deploys
+ */
+
+import { createHash } from "node:crypto";
+import {
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import type { CacheStore } from "../ports/store";
+
+export const createFsCacheStore = <V>(dir: string): CacheStore<V> => {
+	mkdirSync(dir, { recursive: true });
+
+	const fileOf = (key: string): string =>
+		join(
+			dir,
+			`${createHash("sha256").update(key).digest("hex").slice(0, 24)}.json`,
+		);
+
+	const read = (key: string): V | undefined => {
+		const file = fileOf(key);
+		if (!existsSync(file)) return undefined;
+		try {
+			return JSON.parse(readFileSync(file, "utf8")) as V;
+		} catch {
+			return undefined;
+		}
+	};
+
+	return {
+		get: read,
+		set: (key, value) => writeFileSync(fileOf(key), JSON.stringify(value)),
+		delete: (key) => {
+			const file = fileOf(key);
+			if (!existsSync(file)) return false;
+			rmSync(file);
+			return true;
+		},
+		keys: () =>
+			readdirSync(dir)
+				.filter((f) => f.endsWith(".json"))
+				.map((f) => f),
+		clear: () => {
+			for (const file of readdirSync(dir)) {
+				if (file.endsWith(".json")) rmSync(join(dir, file));
+			}
+		},
+	};
+};

package/src/app/modules/cache/adapters/memory.ts

@@ -0,0 +1,13 @@
+import type { CacheStore } from "../ports/store";
+
+/** In-process cache store — the default */
+export const createMemoryStore = <V>(): CacheStore<V> => {
+	const map = new Map<string, V>();
+	return {
+		get: (key) => map.get(key),
+		set: (key, value) => void map.set(key, value),
+		delete: (key) => map.delete(key),
+		keys: () => [...map.keys()],
+		clear: () => map.clear(),
+	};
+};