@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/actions/modules/action/index.ts

@@ -0,0 +1,2 @@
+export * from "./adapters/http/handler";
+export * from "./application";

package/src/actions/presentation/index.ts

@@ -0,0 +1 @@
+export * from "./useSubmission";

package/src/actions/presentation/useSubmission.ts

@@ -0,0 +1,46 @@
+/**
+ * useSubmission
+ * Track pending/result/error state for an action call — Solid accessor
+ */
+
+import { type Accessor, createSignal } from "solid-js";
+import type { Action } from "#actions/modules/action/application/usecases";
+import type { Submission } from "#actions/types";
+
+export interface SubmissionHandle<TInput, TOutput> {
+	submission: Accessor<Submission<TOutput>>;
+	submit(input: TInput): Promise<TOutput | undefined>;
+	clear(): void;
+}
+
+export const useSubmit = <TInput, TOutput>(
+	action: Action<TInput, TOutput>,
+): SubmissionHandle<TInput, TOutput> => {
+	const [submission, setSubmission] = createSignal<Submission<TOutput>>({
+		pending: false,
+	});
+
+	const submit = async (input: TInput): Promise<TOutput | undefined> => {
+		setSubmission({ pending: true });
+		try {
+			const result = await action(input);
+			setSubmission({ pending: false, result });
+			return result;
+		} catch (error) {
+			setSubmission({
+				pending: false,
+				error: error instanceof Error ? error : new Error(String(error)),
+			});
+			return undefined;
+		}
+	};
+
+	return {
+		submission,
+		submit,
+		clear: () => setSubmission({ pending: false }),
+	};
+};
+
+/** @deprecated renamed to useSubmit — useSubmission is SolidStart's name */
+export const useSubmission = useSubmit;

package/src/actions/types/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Actions Domain Types
+ * Mutations + progressive-enhancement forms — the Server Actions equivalent
+ */
+
+export interface ActionContext {
+	request: Request;
+	formData?: FormData;
+}
+
+export type ActionHandler<TInput, TOutput> = (
+	input: TInput,
+	context: ActionContext,
+) => Promise<TOutput> | TOutput;
+
+export interface ActionDescriptor<TInput, TOutput> {
+	id: string;
+	handler: ActionHandler<TInput, TOutput>;
+}
+
+/**
+ * Attributes spread onto a <form> for progressive enhancement —
+ * without JS the browser posts FormData to the action endpoint
+ */
+export interface FormActionProps {
+	action: string;
+	method: "post";
+	enctype: "application/x-www-form-urlencoded";
+}
+
+export interface Submission<TOutput> {
+	pending: boolean;
+	result?: TOutput;
+	error?: Error;
+}

package/src/app/index.ts

@@ -0,0 +1,126 @@
+// Public API - @wrikka/solid-framework/app
+
+// static serving is server-only (node:path) — not re-exported here so
+// client bundles never touch node builtins; get it from the server
+// subpath or via createAppServer config
+export {
+	type ClientComponentProps,
+	defineClientComponent,
+	type SerializableProps,
+} from "#render";
+export * from "./modules/ai";
+export * from "./modules/api-docs";
+export * from "./modules/app-def";
+export * from "./modules/auth";
+export * from "./modules/cache";
+export * from "./modules/config";
+export * from "./modules/content";
+export * from "./modules/conventions";
+export * from "./modules/db";
+export * from "./modules/deploy";
+export * from "./modules/draft";
+export * from "./modules/env";
+// file-routes: curated public surface — plumbing lives in
+// @wrikka/solid-framework/internal
+export {
+	type ApiCallOptions,
+	type ApiClient,
+	ApiError,
+	type ApiMethod,
+	type ApiRouteContext,
+	type ApiRouteHandler,
+	type ApiRouteModule,
+	type ApiRouteModules,
+	type AppLocation,
+	AppRoutes,
+	content,
+	contentMeta,
+	type DeferOptions,
+	type Deferred,
+	DevtoolsOverlay,
+	type DevtoolsOverlayProps,
+	defer,
+	deferAll,
+	deferredRegistry,
+	extractDeferred,
+	type FileRoute,
+	type FileRouteMatch,
+	type FileRoutesProps,
+	Form,
+	type FormProps,
+	type FormState,
+	type GeneratedApiPaths,
+	type GeneratedRoutes,
+	type GeneratedSearch,
+	type GenerateStaticParamsFn,
+	getNavBudget,
+	type HasParams,
+	isDeferred,
+	isLoaderError,
+	isNotFoundError,
+	isRouteDef,
+	Link,
+	type LinkProps,
+	LoaderError,
+	link,
+	NotFoundError,
+	normalizeRouteModule,
+	notFound,
+	type Optimistic,
+	Outlet,
+	orderDeferred,
+	type ParamsFor,
+	type PreloadRoute,
+	page,
+	pathFor,
+	type RouteActionContext,
+	type RouteActionFn,
+	type RouteComponentProps,
+	type RouteDef,
+	type RouteHeadContext,
+	type RouteHeadInput,
+	type RouteLoaderFn,
+	type RouteManifest,
+	type RouteModule,
+	type RouteModules,
+	type RouteParamsFor,
+	type RoutePath,
+	type RouteStatus,
+	redirect,
+	relativePath,
+	renderMarkdown,
+	type SearchFor,
+	ServerComponent,
+	type ServerComponentProps,
+	setNavBudget,
+	type UseAction,
+	type UseRoute,
+	useAction,
+	useFormState,
+	useLoaderRetry,
+	useLocation,
+	useNav,
+	useNavigate,
+	useNavTree,
+	useOptimistic,
+	useParams,
+	usePrefetch,
+	usePreloadRoute,
+	useRawRequest,
+	useRequestState,
+	useRoute,
+	useRouteData,
+	useSearchParams,
+	useSlot,
+} from "./modules/file-routes";
+export * from "./modules/flash";
+export * from "./modules/fonts";
+export * from "./modules/i18n";
+export * from "./modules/middleware";
+export * from "./modules/route-rules";
+export * from "./modules/runtime-config";
+export * from "./modules/seo";
+export * from "./modules/server-entry";
+export * from "./modules/session";
+export * from "./presentation";
+export * from "./types";

package/src/app/modules/ai/domain/operations/handler.ts

@@ -0,0 +1,46 @@
+/**
+ * AI surface — `/llms.txt` (GET) + `/_server/mcp` (POST)
+ * Options enable each independently; wired by createAppServer.
+ */
+
+import type { RouteManifest } from "#app/modules/file-routes/domain/models";
+import type { ApiRouteModules } from "#app/modules/file-routes/domain/operations/api";
+import { type LlmsTxtOptions, llmsTxt } from "./llms";
+import { createMcpHandler } from "./mcp";
+
+export interface AiSurfaceOptions {
+	/** GET /llms.txt — pass false to disable */
+	llmsTxt?: LlmsTxtOptions | false;
+	/** POST /_server/mcp — pass false to disable, or {token} for Bearer auth */
+	mcp?: boolean | { token?: string };
+}
+
+export const createAiHandler = (
+	manifest: RouteManifest,
+	modules: ApiRouteModules,
+	options: AiSurfaceOptions = {},
+): ((request: Request) => Promise<Response | null>) => {
+	const mcp =
+		options.mcp !== false
+			? createMcpHandler(
+					manifest,
+					modules,
+					typeof options.mcp === "object" ? options.mcp : {},
+				)
+			: null;
+	const body =
+		options.llmsTxt === false
+			? undefined
+			: llmsTxt(manifest, options.llmsTxt ?? {});
+
+	return async (request) => {
+		const { pathname } = new URL(request.url);
+		if (body !== undefined && pathname === "/llms.txt") {
+			return new Response(body, {
+				headers: { "Content-Type": "text/plain; charset=utf-8" },
+			});
+		}
+		if (mcp) return mcp(request);
+		return null;
+	};
+};

package/src/app/modules/ai/domain/operations/llms.ts

@@ -0,0 +1,54 @@
+/**
+ * llms.txt — AI-readable site manifest (llmstxt.org convention)
+ * Lists every page route and API endpoint so agents/crawlers can
+ * discover the app's surface without parsing HTML.
+ *
+ *   llmsTxt(manifest, { title: "Shop", origin: "https://x.dev" })
+ */
+
+import type { RouteManifest } from "#app/modules/file-routes/domain/models";
+
+export interface LlmsTxtOptions {
+	/** Site title — becomes the H1 */
+	title?: string;
+	/** One-paragraph summary */
+	description?: string;
+	/** Absolute origin for full URLs */
+	origin?: string;
+	/** Extra link sections appended verbatim */
+	sections?: { title: string; links: { label: string; url: string }[] }[];
+}
+
+export const llmsTxt = (
+	manifest: RouteManifest,
+	options: LlmsTxtOptions = {},
+): string => {
+	const lines: string[] = [];
+	lines.push(`# ${options.title ?? "Site"}`);
+	if (options.description) lines.push("", `> ${options.description}`);
+
+	const pages = manifest
+		.filter((r) => r.kind !== "api")
+		.map((r) => r.path)
+		.sort();
+	const apis = manifest
+		.filter((r) => r.kind === "api")
+		.map((r) => r.path)
+		.sort();
+	const link = (path: string) =>
+		options.origin ? `${options.origin}${path}` : path;
+
+	if (pages.length) {
+		lines.push("", "## Pages", "");
+		for (const p of pages) lines.push(`- [${p}](${link(p)})`);
+	}
+	if (apis.length) {
+		lines.push("", "## API", "");
+		for (const p of apis) lines.push(`- ${link(p)}`);
+	}
+	for (const s of options.sections ?? []) {
+		lines.push("", `## ${s.title}`, "");
+		for (const l of s.links) lines.push(`- [${l.label}](${l.url})`);
+	}
+	return `${lines.join("\n")}\n`;
+};

package/src/app/modules/ai/domain/operations/mcp.ts

@@ -0,0 +1,134 @@
+/**
+ * MCP endpoint — `/_server/mcp` exposes the app's GET api routes as
+ * MCP tools (JSON-RPC 2.0). Agents can `tools/list` to discover
+ * endpoints and `tools/call` to invoke one with query/path params.
+ *
+ * Minimal surface: initialize / tools/list / tools/call.
+ */
+
+import type { RouteManifest } from "#app/modules/file-routes/domain/models";
+import type { ApiRouteModules } from "#app/modules/file-routes/domain/operations/api";
+import { matchFileRoute } from "#app/modules/file-routes/domain/operations/match";
+
+const MCP_ENDPOINT = "/_server/mcp";
+
+interface JsonRpc {
+	jsonrpc: "2.0";
+	id?: number | string | null;
+	method: string;
+	params?: Record<string, unknown>;
+}
+
+const reply = (id: JsonRpc["id"], result: unknown): Response =>
+	new Response(JSON.stringify({ jsonrpc: "2.0", id, result }), {
+		headers: { "Content-Type": "application/json" },
+	});
+
+const rpcError = (id: JsonRpc["id"], code: number, message: string): Response =>
+	new Response(
+		JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }),
+		{ headers: { "Content-Type": "application/json" } },
+	);
+
+const toolName = (path: string): string =>
+	`get_${path.replace(/^\/+|\/+$/g, "").replace(/[^a-zA-Z0-9]+/g, "_") || "root"}`;
+
+export interface McpOptions {
+	/** Bearer token required on `/_server/mcp` — recommended in production */
+	token?: string;
+}
+
+export const createMcpHandler = (
+	manifest: RouteManifest,
+	modules: ApiRouteModules,
+	options: McpOptions = {},
+): ((request: Request) => Promise<Response | null>) => {
+	const apiRoutes = manifest.filter((r) => r.kind === "api");
+
+	return async (request) => {
+		const { pathname } = new URL(request.url);
+		if (pathname !== MCP_ENDPOINT) return null;
+		if (request.method !== "POST") {
+			return rpcError(null, -32600, "MCP endpoint expects POST");
+		}
+		if (options.token) {
+			const auth = request.headers.get("authorization");
+			if (auth !== `Bearer ${options.token}`) {
+				return new Response("unauthorized", { status: 401 });
+			}
+		}
+
+		const msg = (await request.json().catch(() => null)) as JsonRpc | null;
+		if (msg?.jsonrpc !== "2.0") return rpcError(null, -32700, "Parse error");
+
+		switch (msg.method) {
+			case "initialize":
+				return reply(msg.id, {
+					protocolVersion: "2025-06-18",
+					capabilities: { tools: {} },
+					serverInfo: { name: "solid-framework", version: "0.3.1" },
+				});
+
+			case "notifications/initialized":
+				return new Response(null, { status: 202 });
+
+			case "tools/list":
+				return reply(msg.id, {
+					tools: apiRoutes.map((r) => ({
+						name: toolName(r.path),
+						description: `GET ${r.path}`,
+						inputSchema: {
+							type: "object",
+							properties: Object.fromEntries(
+								r.params.map((p) => [
+									p,
+									{ type: "string", description: `path param :${p}` },
+								]),
+							),
+							additionalProperties: true,
+						},
+					})),
+				});
+
+			case "tools/call": {
+				const name = msg.params?.name as string | undefined;
+				const args = (msg.params?.arguments ?? {}) as Record<string, unknown>;
+				const route = apiRoutes.find((r) => toolName(r.path) === name);
+				if (!route) return rpcError(msg.id, -32602, `unknown tool ${name}`);
+
+				// Fill path params; the rest become query params
+				let path = route.path;
+				const query = new URLSearchParams();
+				for (const [k, v] of Object.entries(args)) {
+					if (path.includes(`:${k}`) || path.includes(`*${k}`)) {
+						path = path.replace(`:${k}`, String(v)).replace(`*${k}`, String(v));
+					} else query.set(k, String(v));
+				}
+				const origin = new URL(request.url).origin;
+				const match = matchFileRoute(path, apiRoutes, "api");
+				if (!match) return rpcError(msg.id, -32602, "unmatched params");
+				const entry =
+					modules[match.route.file] ?? modules[`/${match.route.file}`];
+				if (!entry) return rpcError(msg.id, -32603, "module unavailable");
+				const mod = await Promise.resolve(
+					typeof entry === "function" ? entry() : entry,
+				);
+				const handler = (mod.GET ?? mod.default) as
+					| ((req: Request, ctx: { params: Record<string, string> }) => unknown)
+					| undefined;
+				if (!handler) return rpcError(msg.id, -32601, "no GET handler");
+				const res = await handler(new Request(`${origin}${path}?${query}`), {
+					params: match.params,
+				});
+				const body =
+					res instanceof Response ? await res.text() : JSON.stringify(res);
+				return reply(msg.id, {
+					content: [{ type: "text", text: body }],
+				});
+			}
+
+			default:
+				return rpcError(msg.id, -32601, `method ${msg.method} not supported`);
+		}
+	};
+};

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

@@ -0,0 +1,3 @@
+export * from "./domain/operations/handler";
+export * from "./domain/operations/llms";
+export * from "./domain/operations/mcp";

package/src/app/modules/api-docs/domain/operations/openapi.ts

@@ -0,0 +1,113 @@
+/**
+ * OpenAPI Generation
+ * Emit a minimal OpenAPI 3.1 document from `*.api.ts` manifest entries —
+ * method exports become operations; :param segments become path
+ * parameters. Served at `/_docs/openapi.json`
+ */
+
+import type { RouteManifest } from "#app/modules/file-routes/domain/models";
+import type { ApiRouteModules } from "#app/modules/file-routes/domain/operations";
+
+const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+
+interface OpenApiOperation {
+	operationId: string;
+	responses: Record<string, { description: string }>;
+	parameters?: {
+		name: string;
+		in: "path";
+		required: true;
+		schema: { type: "string" };
+	}[];
+}
+
+interface OpenApiDoc {
+	openapi: "3.1.0";
+	info: { title: string; version: string };
+	paths: Record<string, Record<string, OpenApiOperation>>;
+}
+
+const toOpenApiPath = (path: string): string =>
+	path
+		.split("/")
+		.map((seg) =>
+			seg.startsWith(":")
+				? `{${seg.slice(1)}}`
+				: seg.startsWith("*")
+					? "{path}"
+					: seg,
+		)
+		.join("/");
+
+export const generateOpenApi = async (
+	manifest: RouteManifest,
+	modules: ApiRouteModules,
+	options: { title?: string; version?: string } = {},
+): Promise<OpenApiDoc> => {
+	const doc: OpenApiDoc = {
+		openapi: "3.1.0",
+		info: {
+			title: options.title ?? "API",
+			version: options.version ?? "0.0.0",
+		},
+		paths: {},
+	};
+
+	for (const route of manifest) {
+		if (route.kind !== "api") continue;
+		const entry = modules[route.file] ?? modules[`/${route.file}`];
+		if (!entry) continue;
+		const mod = (await Promise.resolve(
+			typeof entry === "function" ? entry() : entry,
+		)) as Record<string, unknown>;
+
+		const params = route.path
+			.split("/")
+			.filter((s) => s.startsWith(":") || s.startsWith("*"))
+			.map((s) => ({
+				name: s.slice(1),
+				in: "path" as const,
+				required: true as const,
+				schema: { type: "string" as const },
+			}));
+
+		const pathItem: Record<string, OpenApiOperation> = {};
+		const opBase =
+			route.path.replaceAll("/", ".").replaceAll(":", "_") || ".root";
+		for (const method of METHODS) {
+			if (typeof mod[method] !== "function") continue;
+			pathItem[method.toLowerCase()] = {
+				operationId: `${method.toLowerCase()}${opBase}`,
+				responses: { "200": { description: "Success" } },
+				...(params.length ? { parameters: params } : {}),
+			};
+		}
+		if (typeof mod.default === "function" && !pathItem.get) {
+			pathItem.get = {
+				operationId: `get${opBase}`,
+				responses: { "200": { description: "Success" } },
+				...(params.length ? { parameters: params } : {}),
+			};
+		}
+		if (Object.keys(pathItem).length) {
+			doc.paths[toOpenApiPath(route.path)] = pathItem;
+		}
+	}
+	return doc;
+};
+
+export const DOCS_ENDPOINT = "/_docs/openapi.json";
+
+/** Handler serving the generated spec — null for other paths */
+export const createApiDocsHandler = (
+	manifest: RouteManifest,
+	modules: ApiRouteModules,
+	options: { title?: string; version?: string } = {},
+): ((request: Request) => Promise<Response | null>) => {
+	let cached: Promise<OpenApiDoc> | undefined;
+	return async (request: Request) => {
+		if (new URL(request.url).pathname !== DOCS_ENDPOINT) return null;
+		cached ??= generateOpenApi(manifest, modules, options);
+		return Response.json(await cached);
+	};
+};

package/src/app/modules/api-docs/index.ts

@@ -0,0 +1 @@
+export * from "./domain/operations/openapi";