@ecopages/core 0.2.0-alpha.5 → 0.2.0-alpha.7

package/src/adapters/node/static-content-server.ts

@@ -10,11 +10,22 @@ type NodeStaticContentServerOptions = {
 	port?: number;
 };
 
+/**
+ * Serves prebuilt static Ecopages output through Node's HTTP server.
+ *
+ * @remarks
+ * This server is used by the Node preview/build path once the app has already
+ * emitted its static output. It intentionally stays small: path sanitization,
+ * content-type selection, optional gzip serving, and 404 handling.
+ */
 export class NodeStaticContentServer {
 	private readonly appConfig: EcoPagesAppConfig;
 	private readonly options: NodeStaticContentServerOptions;
 	private server: NodeHttpServer | null = null;
 
+	/**
+	 * Creates the Node static-content server for one built app output directory.
+	 */
 	constructor({ appConfig, options }: { appConfig: EcoPagesAppConfig; options?: NodeStaticContentServerOptions }) {
 		this.appConfig = appConfig;
 		this.options = {
@@ -23,10 +34,17 @@ export class NodeStaticContentServer {
 		};
 	}
 
+	/**
+	 * Returns whether the given content type should be served from a pre-gzipped
+	 * companion file when available.
+	 */
 	private shouldServeGzip(contentType: string): boolean {
 		return ['text/javascript', 'text/css'].includes(contentType);
 	}
 
+	/**
+	 * Normalizes a request pathname and rejects directory traversal attempts.
+	 */
 	private sanitizePath(pathname: string): string | null {
 		const withoutLeadingSlash = pathname.replace(/^\/+/, '');
 		const normalizedPath = normalize(withoutLeadingSlash);
@@ -38,6 +56,9 @@ export class NodeStaticContentServer {
 		return normalizedPath;
 	}
 
+	/**
+	 * Writes one HTTP response with the provided headers and optional body.
+	 */
 	private sendResponse(res: ServerResponse, status: number, headers: Record<string, string>, body?: Buffer): void {
 		res.statusCode = status;
 		for (const [key, value] of Object.entries(headers)) {
@@ -52,6 +73,9 @@ export class NodeStaticContentServer {
 		res.end(body);
 	}
 
+	/**
+	 * Serves the generated 404 page when present, or a plain-text fallback.
+	 */
 	private sendNotFoundPage(req: IncomingMessage, res: ServerResponse): void {
 		const error404TemplatePath = join(this.appConfig.absolutePaths.distDir, '404.html');
 		const isHead = (req.method ?? 'GET').toUpperCase() === 'HEAD';
@@ -70,6 +94,9 @@ export class NodeStaticContentServer {
 		this.sendResponse(res, 404, { 'Content-Type': 'text/html' }, isHead ? undefined : file);
 	}
 
+	/**
+	 * Serves one concrete file path, honoring gzip and HEAD semantics.
+	 */
 	private serveFile(req: IncomingMessage, res: ServerResponse, filePath: string, status = 200): void {
 		const contentType = ServerUtils.getContentType(extname(filePath));
 		const acceptsGzip = req.headers['accept-encoding']?.includes('gzip');
@@ -102,6 +129,9 @@ export class NodeStaticContentServer {
 		this.sendResponse(res, status, { 'Content-Type': contentType }, isHead ? undefined : file);
 	}
 
+	/**
+	 * Handles one incoming Node HTTP request against the built static output tree.
+	 */
 	private handleRequest(req: IncomingMessage, res: ServerResponse): void {
 		const method = (req.method ?? 'GET').toUpperCase();
 		const isHead = method === 'HEAD';
@@ -161,6 +191,9 @@ export class NodeStaticContentServer {
 		this.sendNotFoundPage(req, res);
 	}
 
+	/**
+	 * Starts the static preview server.
+	 */
 	public async start(): Promise<NodeHttpServer> {
 		if (this.server) {
 			return this.server;
@@ -177,6 +210,9 @@ export class NodeStaticContentServer {
 		return this.server;
 	}
 
+	/**
+	 * Stops the static preview server and optionally closes active connections.
+	 */
 	public async stop(force = true): Promise<void> {
 		if (!this.server) {
 			return;

package/src/adapters/node/write-runtime-manifest.ts

@@ -0,0 +1,38 @@
+import {
+	writeAppNodeRuntimeManifest,
+	type NodeRuntimeManifest,
+} from '../../services/runtime-manifest/node-runtime-manifest.service.ts';
+
+/**
+ * Writes the app-owned Node runtime manifest from a bundled manifest-writer
+ * entrypoint.
+ *
+ * @remarks
+ * The Node thin-host launch plan executes a bundled JavaScript prep artifact
+ * instead of evaluating TypeScript config directly in the launcher. This helper
+ * is the narrow bridge between that bundle and the core-owned manifest writer.
+ */
+export function writeBundledNodeRuntimeManifest(
+	appConfig: {
+		rootDir: string;
+		absolutePaths: {
+			config: string;
+			srcDir: string;
+			distDir: string;
+			workDir?: string;
+		};
+		loaders: Map<string, unknown>;
+		runtime?: {
+			nodeRuntimeManifest?: NodeRuntimeManifest;
+		};
+	},
+	options: {
+		entryModulePath: string;
+		manifestFilePath: string;
+	},
+): void {
+	writeAppNodeRuntimeManifest(appConfig as never, {
+		entryModulePath: options.entryModulePath,
+		manifestFilePath: options.manifestFilePath,
+	});
+}

package/src/adapters/shared/api-response.test.ts

@@ -0,0 +1,97 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { ApiResponseBuilder } from './api-response';
+
+describe('ApiResponseBuilder', () => {
+	let builder: ApiResponseBuilder;
+
+	beforeEach(() => {
+		builder = new ApiResponseBuilder();
+	});
+
+	describe('json()', () => {
+		it('should create JSON response with correct content type and data', async () => {
+			const data = { foo: 'bar' };
+			const response = builder.json(data);
+
+			expect(response.headers.get('Content-Type')).toBe('application/json; charset=utf-8');
+			expect(await response.json()).toEqual(data);
+			expect(response.status).toBe(200);
+		});
+	});
+
+	describe('text()', () => {
+		it('should create text response with correct content type and data', async () => {
+			const text = 'Hello World';
+			const response = builder.text(text);
+
+			expect(response.headers.get('Content-Type')).toBe('text/plain; charset=utf-8');
+			expect(await response.text()).toBe(text);
+			expect(response.status).toBe(200);
+		});
+	});
+
+	describe('html()', () => {
+		it('should create HTML response with correct content type and data', async () => {
+			const html = '<h1>Hello</h1>';
+			const response = builder.html(html);
+
+			expect(response.headers.get('Content-Type')).toBe('text/html; charset=utf-8');
+			expect(await response.text()).toBe(html);
+			expect(response.status).toBe(200);
+		});
+	});
+
+	describe('status()', () => {
+		it('should set custom status code', () => {
+			const response = builder.status(404).json({ message: 'Not Found' });
+			expect(response.status).toBe(404);
+		});
+	});
+
+	describe('headers()', () => {
+		it('should set custom headers', () => {
+			const response = builder.headers({ 'X-Custom': 'Value' }).json({});
+			expect(response.headers.get('X-Custom')).toBe('Value');
+		});
+	});
+
+	describe('redirect()', () => {
+		it('should create redirect response with location header', () => {
+			const url = 'https://example.com';
+			const response = builder.redirect(url);
+
+			expect(response.headers.get('Location')).toBe(url);
+			expect(response.status).toBe(302);
+		});
+
+		it('should use explicit status for redirect', () => {
+			const response = builder.redirect('https://example.com', 301);
+			expect(response.status).toBe(301);
+		});
+	});
+
+	describe('error()', () => {
+		it('should create JSON error response for object data', async () => {
+			const error = { code: 'ERR_1', message: 'Error occurred' };
+			const response = builder.error(error);
+
+			expect(response.headers.get('Content-Type')).toBe('application/json; charset=utf-8');
+			expect(await response.json()).toEqual({ error });
+			expect(response.status).toBe(500);
+		});
+
+		it('should create text error response for string data', async () => {
+			const error = 'Error occurred';
+			const response = builder.error(error);
+
+			expect(response.headers.get('Content-Type')).toBe('text/plain; charset=utf-8');
+			expect(await response.text()).toBe(error);
+			expect(response.status).toBe(500);
+		});
+
+		it('should use explicit status for error', () => {
+			const response = builder.error('Not Found', 404);
+			expect(response.status).toBe(404);
+		});
+	});
+});

package/src/{define-api-handler.ts → adapters/shared/define-api-handler.ts}

@@ -4,7 +4,7 @@ import type {
 	Middleware,
 	RouteSchema,
 	TypedGroupHandlerContext,
-} from './public-types.ts';
+} from '../../public-types.ts';
 
 type UniversalContext = ApiHandlerContext<Request, unknown>;
 

package/src/adapters/shared/explicit-static-route-matcher.test.ts

@@ -0,0 +1,381 @@
+import { describe, expect, test, vi } from 'vitest';
+import type { EcoPageComponent, StaticRoute, ViewLoader } from '../../public-types.ts';
+import { ExplicitStaticRouteMatcher } from './explicit-static-route-matcher.ts';
+
+function createMockView(integration = 'ghtml'): EcoPageComponent<any> {
+	const view = (() => '<div>Test</div>') as EcoPageComponent<any>;
+	view.config = {
+		integration,
+		__eco: { id: 'test', file: '/test/-view.ts', integration },
+	};
+	return view;
+}
+
+function createMockLoader(view?: EcoPageComponent<any>): ViewLoader<any> {
+	const actualView = view ?? createMockView();
+	return () => Promise.resolve({ default: actualView });
+}
+
+function createMockRoute(path: string, view?: EcoPageComponent<any>): StaticRoute {
+	return {
+		path,
+		loader: createMockLoader(view),
+	};
+}
+
+function createMatcher(staticRoutes: StaticRoute[]) {
+	return new ExplicitStaticRouteMatcher({
+		appConfig: { baseUrl: 'http://localhost:3000' } as any,
+		routeRendererFactory: {} as any,
+		staticRoutes,
+	});
+}
+
+describe('ExplicitStaticRouteMatcher', () => {
+	describe('match', () => {
+		test('should match exact static path', () => {
+			const matcher = createMatcher([createMockRoute('/about')]);
+
+			const result = matcher.match('http://localhost:3000/about');
+
+			expect(result).not.toBeNull();
+			expect(result?.route.path).toBe('/about');
+			expect(result?.params).toEqual({});
+		});
+
+		test('should match root path', () => {
+			const matcher = createMatcher([createMockRoute('/')]);
+
+			const result = matcher.match('http://localhost:3000/');
+
+			expect(result).not.toBeNull();
+			expect(result?.route.path).toBe('/');
+			expect(result?.params).toEqual({});
+		});
+
+		test('should match nested static path', () => {
+			const matcher = createMatcher([createMockRoute('/docs/getting-started')]);
+
+			const result = matcher.match('http://localhost:3000/docs/getting-started');
+
+			expect(result).not.toBeNull();
+			expect(result?.route.path).toBe('/docs/getting-started');
+		});
+
+		test('should return null for non-matching path', () => {
+			const matcher = createMatcher([createMockRoute('/about')]);
+
+			const result = matcher.match('http://localhost:3000/contact');
+
+			expect(result).toBeNull();
+		});
+
+		test('should return null for partial match', () => {
+			const matcher = createMatcher([createMockRoute('/about')]);
+
+			const result = matcher.match('http://localhost:3000/about/team');
+
+			expect(result).toBeNull();
+		});
+	});
+
+	describe('match with :param syntax', () => {
+		test('should match dynamic segment with colon syntax', () => {
+			const matcher = createMatcher([createMockRoute('/blog/:slug')]);
+
+			const result = matcher.match('http://localhost:3000/blog/hello-world');
+
+			expect(result).not.toBeNull();
+			expect(result?.params).toEqual({ slug: 'hello-world' });
+		});
+
+		test('should match multiple dynamic segments', () => {
+			const matcher = createMatcher([createMockRoute('/blog/:year/:month/:slug')]);
+
+			const result = matcher.match('http://localhost:3000/blog/2024/01/hello-world');
+
+			expect(result).not.toBeNull();
+			expect(result?.params).toEqual({
+				year: '2024',
+				month: '01',
+				slug: 'hello-world',
+			});
+		});
+
+		test('should match mixed static and dynamic segments', () => {
+			const matcher = createMatcher([createMockRoute('/users/:id/posts')]);
+
+			const result = matcher.match('http://localhost:3000/users/123/posts');
+
+			expect(result).not.toBeNull();
+			expect(result?.params).toEqual({ id: '123' });
+		});
+	});
+
+	describe('match with [param] syntax', () => {
+		test('should match dynamic segment with bracket syntax', () => {
+			const matcher = createMatcher([createMockRoute('/blog/[slug]')]);
+
+			const result = matcher.match('http://localhost:3000/blog/hello-world');
+
+			expect(result).not.toBeNull();
+			expect(result?.params).toEqual({ slug: 'hello-world' });
+		});
+
+		test('should match multiple bracket parameters', () => {
+			const matcher = createMatcher([createMockRoute('/products/[category]/[id]')]);
+
+			const result = matcher.match('http://localhost:3000/products/electronics/12345');
+
+			expect(result).not.toBeNull();
+			expect(result?.params).toEqual({
+				category: 'electronics',
+				id: '12345',
+			});
+		});
+	});
+
+	describe('match with catch-all routes', () => {
+		test('should match catch-all with bracket syntax', () => {
+			const matcher = createMatcher([createMockRoute('/docs/[...path]')]);
+
+			const result = matcher.match('http://localhost:3000/docs/api/reference/components');
+
+			expect(result).not.toBeNull();
+			expect(result?.params).toEqual({ path: 'api/reference/components' });
+		});
+
+		test('should match catch-all with colon syntax', () => {
+			const matcher = createMatcher([createMockRoute('/files/:...path')]);
+
+			const result = matcher.match('http://localhost:3000/files/images/2024/photo.jpg');
+
+			expect(result).not.toBeNull();
+			expect(result?.params).toEqual({ path: 'images/2024/photo.jpg' });
+		});
+
+		test('should match catch-all with single segment', () => {
+			const matcher = createMatcher([createMockRoute('/docs/[...path]')]);
+
+			const result = matcher.match('http://localhost:3000/docs/intro');
+
+			expect(result).not.toBeNull();
+			expect(result?.params).toEqual({ path: 'intro' });
+		});
+	});
+
+	describe('route priority', () => {
+		test('should match first route when multiple routes match', () => {
+			const aboutView = createMockView();
+			const catchAllView = createMockView();
+
+			const matcher = createMatcher([
+				createMockRoute('/about', aboutView),
+				createMockRoute('/[...path]', catchAllView),
+			]);
+
+			const result = matcher.match('http://localhost:3000/about');
+
+			expect(result).not.toBeNull();
+			expect(result?.route.path).toBe('/about');
+		});
+
+		test('should match exact route before dynamic route', () => {
+			const exactView = createMockView();
+			const dynamicView = createMockView();
+
+			const matcher = createMatcher([
+				createMockRoute('/blog/featured', exactView),
+				createMockRoute('/blog/:slug', dynamicView),
+			]);
+
+			const result = matcher.match('http://localhost:3000/blog/featured');
+
+			expect(result).not.toBeNull();
+			expect(result?.route.path).toBe('/blog/featured');
+		});
+	});
+
+	describe('edge cases', () => {
+		test('should handle URL with query parameters', () => {
+			const matcher = createMatcher([createMockRoute('/search')]);
+
+			const result = matcher.match('http://localhost:3000/search?q=test&page=1');
+
+			expect(result).not.toBeNull();
+			expect(result?.route.path).toBe('/search');
+		});
+
+		test('should handle URL with hash', () => {
+			const matcher = createMatcher([createMockRoute('/docs/intro')]);
+
+			const result = matcher.match('http://localhost:3000/docs/intro#section-1');
+
+			expect(result).not.toBeNull();
+			expect(result?.route.path).toBe('/docs/intro');
+		});
+
+		test('should handle trailing slash', () => {
+			const matcher = createMatcher([createMockRoute('/about')]);
+
+			const result = matcher.match('http://localhost:3000/about/');
+
+			expect(result).not.toBeNull();
+			expect(result?.route.path).toBe('/about');
+		});
+
+		test('should return null for empty routes array', () => {
+			const matcher = createMatcher([]);
+
+			const result = matcher.match('http://localhost:3000/anything');
+
+			expect(result).toBeNull();
+		});
+	});
+
+	describe('handleMatch', () => {
+		test('should accept integration metadata from view.config.integration', async () => {
+			const view = (() => '<div>Test</div>') as EcoPageComponent<any>;
+			view.config = {
+				integration: 'ghtml',
+				__eco: { id: 'test', file: '/test/-view.ts', integration: 'ghtml' },
+			};
+
+			const mockResponse = new Response('<html>Test</html>');
+			const renderToResponse = vi.fn(() => mockResponse);
+			const matcher = new ExplicitStaticRouteMatcher({
+				appConfig: { baseUrl: 'http://localhost:3000' } as any,
+				routeRendererFactory: {
+					getRendererByIntegration: vi.fn(() => ({
+						renderToResponse,
+					})),
+				} as any,
+				staticRoutes: [createMockRoute('/about', view)],
+			});
+
+			const match = matcher.match('http://localhost:3000/about');
+			const response = await matcher.handleMatch(match!);
+
+			expect(response).toBe(mockResponse);
+			expect(renderToResponse).toHaveBeenCalledWith(view, {}, {});
+		});
+
+		test('should throw error when view is missing __eco.integration', async () => {
+			const viewWithoutIntegration = (() => '<div>Test</div>') as EcoPageComponent<any>;
+			viewWithoutIntegration.config = {
+				__eco: undefined,
+			};
+
+			const matcher = new ExplicitStaticRouteMatcher({
+				appConfig: { baseUrl: 'http://localhost:3000' } as any,
+				routeRendererFactory: {
+					getRendererByIntegration: vi.fn(() => null),
+				} as any,
+				staticRoutes: [createMockRoute('/about', viewWithoutIntegration)],
+			});
+			const match = matcher.match('http://localhost:3000/about');
+
+			expect(match).not.toBeNull();
+			await expect(matcher.handleMatch(match!)).rejects.toThrow('missing __eco.integration');
+		});
+
+		test('should throw error when renderer is not found', async () => {
+			const view = createMockView('nonexistent-integration');
+			const RendererFactory = {
+				getRendererByIntegration: vi.fn(() => null),
+			};
+
+			const matcher = new ExplicitStaticRouteMatcher({
+				appConfig: { baseUrl: 'http://localhost:3000' } as any,
+				routeRendererFactory: RendererFactory as any,
+				staticRoutes: [createMockRoute('/about', view)],
+			});
+
+			const match = matcher.match('http://localhost:3000/about');
+
+			await expect(matcher.handleMatch(match!)).rejects.toThrow(
+				'No renderer found for integration: nonexistent-integration',
+			);
+		});
+
+		test('should call renderer.renderToResponse with correct arguments', async () => {
+			const view = createMockView('ghtml');
+			const mockResponse = new Response('<html>Test</html>');
+			const RenderToResponse = vi.fn(() => mockResponse);
+			const RendererFactory = {
+				getRendererByIntegration: vi.fn(() => ({
+					renderToResponse: RenderToResponse,
+				})),
+			};
+
+			const matcher = new ExplicitStaticRouteMatcher({
+				appConfig: { baseUrl: 'http://localhost:3000' } as any,
+				routeRendererFactory: RendererFactory as any,
+				staticRoutes: [createMockRoute('/about', view)],
+			});
+
+			const match = matcher.match('http://localhost:3000/about');
+			const response = await matcher.handleMatch(match!);
+
+			expect(response).toBe(mockResponse);
+			expect(RenderToResponse).toHaveBeenCalledTimes(1);
+			expect(RenderToResponse).toHaveBeenCalledWith(view, {}, {});
+		});
+
+		test('should resolve staticProps and pass to renderer', async () => {
+			const view = createMockView('ghtml');
+			view.staticProps = vi.fn(async () => ({
+				props: { title: 'About Page', content: 'Hello' },
+			}));
+
+			const mockResponse = new Response('<html>Test</html>');
+			const RenderToResponse = vi.fn(() => mockResponse);
+			const RendererFactory = {
+				getRendererByIntegration: vi.fn(() => ({
+					renderToResponse: RenderToResponse,
+				})),
+			};
+
+			const matcher = new ExplicitStaticRouteMatcher({
+				appConfig: { baseUrl: 'http://localhost:3000' } as any,
+				routeRendererFactory: RendererFactory as any,
+				staticRoutes: [createMockRoute('/about', view)],
+			});
+
+			const match = matcher.match('http://localhost:3000/about');
+			await matcher.handleMatch(match!);
+
+			expect(view.staticProps).toHaveBeenCalledTimes(1);
+			expect(RenderToResponse).toHaveBeenCalledWith(view, { title: 'About Page', content: 'Hello' }, {});
+		});
+
+		test('should pass params to staticProps', async () => {
+			const view = createMockView('ghtml');
+			view.staticProps = vi.fn(async ({ pathname }) => ({
+				props: { slug: pathname.params.slug },
+			}));
+
+			const mockResponse = new Response('<html>Test</html>');
+			const RendererFactory = {
+				getRendererByIntegration: vi.fn(() => ({
+					renderToResponse: vi.fn(() => mockResponse),
+				})),
+			};
+
+			const matcher = new ExplicitStaticRouteMatcher({
+				appConfig: { baseUrl: 'http://localhost:3000' } as any,
+				routeRendererFactory: RendererFactory as any,
+				staticRoutes: [createMockRoute('/blog/:slug', view)],
+			});
+
+			const match = matcher.match('http://localhost:3000/blog/hello-world');
+			await matcher.handleMatch(match!);
+
+			expect(view.staticProps).toHaveBeenCalledWith(
+				expect.objectContaining({
+					pathname: { params: { slug: 'hello-world' } },
+				}),
+			);
+		});
+	});
+});

package/src/adapters/shared/explicit-static-route-matcher.ts

@@ -9,6 +9,12 @@ export const EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS = {
 	noRendererForIntegration: (integrationName: string) => `No renderer found for integration: ${integrationName}`,
 } as const;
 
+function getViewIntegrationName(view: {
+	config?: { integration?: string; __eco?: { integration?: string } };
+}): string | undefined {
+	return view.config?.integration ?? view.config?.__eco?.integration;
+}
+
 export interface ExplicitStaticRouteMatcherOptions {
 	appConfig: EcoPagesAppConfig;
 	routeRendererFactory: RouteRendererFactory;
@@ -102,7 +108,7 @@ export class ExplicitStaticRouteMatcher {
 			const mod = await route.loader();
 			const view = mod.default;
 
-			const integrationName = view.config?.__eco?.integration;
+			const integrationName = getViewIntegrationName(view);
 			if (!integrationName) {
 				throw new Error(EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS.missingIntegration(route.path));
 			}