Orga build (#318)

* [orga-build] add endpoint route support

* address some issues

* cleanup

* update README

* add changeset

* fix build

Author: xiaoxinghu

.changeset/green-poems-yell.md

@@ -0,0 +1,5 @@
+---
+'orga-build': minor
+---
+
+add data endpoint

packages/orga-build/README.org

@@ -93,14 +93,14 @@ export default {
 
 ** Configuration Options
 
-| Option | Type | Default | Description |
-|--------+------+---------+-------------|
-| =root= | =string= | ='pages'= | Directory containing content files |
-| =outDir= | =string= | ='out'= | Output directory for production build |
-| =containerClass= | =string \vert string[]= | =[]= | CSS class(es) for content wrapper |
-| =styles= | =string[]= | =[]= | Global stylesheet URLs injected/imported explicitly |
-| =rehypePlugins= | =PluggableList= | =[]= | Extra rehype plugins appended to orga-build defaults |
-| =vitePlugins= | =PluginOption[]= | =[]= | Additional Vite plugins |
+| Option         | Type              | Default | Description                                          |
+|----------------+-------------------+---------+------------------------------------------------------|
+| =root=           | =string=            | ='pages'= | Directory containing content files                   |
+| =outDir=         | =string=            | ='out'=   | Output directory for production build                |
+| =containerClass= | =string \vert string[]= | =[]=      | CSS class(es) for content wrapper                    |
+| =styles=         | =string[]=          | =[]=      | Global stylesheet URLs injected/imported explicitly  |
+| =rehypePlugins=  | =PluggableList=     | =[]=      | Extra rehype plugins appended to orga-build defaults |
+| =vitePlugins=    | =PluginOption[]=    | =[]=      | Additional Vite plugins                              |
 
 ** Syntax Highlighting Example
 
@@ -112,6 +112,47 @@ export default {
 }
 #+end_src
 
+* Routing
+
+orga-build supports two route types: *page routes* and *endpoint routes*.
+
+** Page Routes
+
+Page routes are discovered from =.org=, =.tsx=, and =.jsx= files.
+
+- =index.org= -> =/=
+- =about.org= -> =/about=
+- =docs/getting-started.tsx= -> =/docs/getting-started=
+
+At build time, page routes are emitted as HTML:
+
+- =/about= -> =out/about/index.html=
+
+** Endpoint Routes
+
+Endpoint routes are discovered from =.ts=, =.js=, =.mts=, and =.mjs= files where the basename already includes a target extension (for example =rss.xml.ts= or =data.json.ts=).
+
+- =rss.xml.ts= -> =/rss.xml=
+- =nested/feed.xml.ts= -> =/nested/feed.xml=
+- =api/data.json.ts= -> =/api/data.json=
+
+Endpoint modules must export:
+
+#+begin_src ts
+export async function GET(ctx) {
+  return new Response('ok', {
+    headers: { 'content-type': 'text/plain; charset=utf-8' }
+  })
+}
+#+end_src
+
+At build time, endpoint routes are emitted to exact filenames:
+
+- =/rss.xml= -> =out/rss.xml=
+- =/api/data.json= -> =out/api/data.json=
+
+Route conflicts (same final route path) fail fast during dev/build startup.
+
 * TypeScript Setup
 
 If you're using TypeScript and want type support for the =orga-build:content= virtual module, you need to add a reference to the type definitions.

packages/orga-build/lib/__tests__/build.test.js

@@ -49,6 +49,19 @@ Here's [[mailto:hi@unclex.net][send me an email]].
 			'Docs index page.'
 		)
 		await fs.writeFile(path.join(fixtureDir, 'more.org'), 'Another page.')
+		await fs.writeFile(
+			path.join(fixtureDir, 'rss.xml.ts'),
+			`import { getPages } from 'orga-build:content'
+
+export function GET() {
+  const pages = getPages()
+  return new Response(
+    '<?xml version="1.0" encoding="UTF-8"?><rss><count>' + pages.length + '</count></rss>',
+    { headers: { 'content-type': 'application/xml; charset=utf-8' } }
+  )
+}
+`
+		)
 		await fs.writeFile(
 			path.join(fixtureDir, 'style.css'),
 			'.global-style-marker { color: rgb(1, 2, 3); }'
@@ -169,4 +182,50 @@ This page verifies custom rehype plugins.`
 			await fs.rm(fixtureDirRehype, { recursive: true, force: true })
 		}
 	})
+
+	test('emits endpoint routes with exact output filenames', async () => {
+		await build({
+			root: fixtureDir,
+			outDir: outDir,
+			containerClass: [],
+			vitePlugins: [],
+			preBuild: [],
+			postBuild: []
+		})
+
+		const rss = await fs.readFile(path.join(outDir, 'rss.xml'), 'utf-8')
+		assert.ok(
+			rss.includes('<rss>') && rss.includes('<count>'),
+			'should emit rss.xml from GET endpoint'
+		)
+	})
+
+	test('fails on duplicate route conflicts', async () => {
+		const fixtureDirConflict = path.join(__dirname, 'fixtures-conflict')
+		const outDirConflict = path.join(__dirname, '.test-output-conflict')
+		try {
+			await fs.mkdir(fixtureDirConflict, { recursive: true })
+			await fs.writeFile(path.join(fixtureDirConflict, 'index.org'), 'Home')
+			await fs.writeFile(
+				path.join(fixtureDirConflict, 'index.tsx'),
+				'export default function Page() { return <div>Index</div> }'
+			)
+
+			await assert.rejects(
+				() =>
+					build({
+						root: fixtureDirConflict,
+						outDir: outDirConflict,
+						containerClass: [],
+						vitePlugins: [],
+						preBuild: [],
+						postBuild: []
+					}),
+				/Route conflict detected/
+			)
+		} finally {
+			await fs.rm(outDirConflict, { recursive: true, force: true })
+			await fs.rm(fixtureDirConflict, { recursive: true, force: true })
+		}
+	})
 })

packages/orga-build/lib/build.js

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises'
 import path from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { createBuilder } from 'vite'
+import { resolveEndpointResponse } from './endpoint.js'
 import { emptyDir, ensureDir, exists } from './fs.js'
 import { alias, createOrgaBuildConfig } from './plugin.js'
 import { escapeHtml } from './util.js'
@@ -83,9 +84,11 @@ export async function build(
 	console.log('preparing ssr bundle...')
 	await builder.build(builder.environments.ssr)
 
-	const { render, pages } = await import(
-		pathToFileURL(path.join(ssrOutDir, 'ssr.mjs')).toString()
-	)
+	const {
+		render,
+		pages,
+		endpoints = {}
+	} = await import(pathToFileURL(path.join(ssrOutDir, 'ssr.mjs')).toString())
 
 	// Build client bundle
 	const _clientResult = await builder.build(builder.environments.client)
@@ -129,6 +132,31 @@ export async function build(
 		})
 	)
 
+	const endpointPaths = Object.keys(endpoints)
+	await Promise.all(
+		endpointPaths.map(async (route) => {
+			const endpointModule = endpoints[route]
+			const ctx = {
+				url: new URL(`http://localhost${route}`),
+				params: {},
+				mode: /** @type {'build'} */ ('build'),
+				route: { route }
+			}
+
+			const response = await resolveEndpointResponse(endpointModule, ctx, 'GET')
+			if (response.status < 200 || response.status >= 300) {
+				throw new Error(
+					`Endpoint route "${route}" returned non-2xx status during build: ${response.status}`
+				)
+			}
+
+			const bytes = Buffer.from(await response.arrayBuffer())
+			const writePath = path.join(clientOutDir, route.replace(/^\//, ''))
+			await ensureDir(path.dirname(writePath))
+			await fs.writeFile(writePath, bytes)
+		})
+	)
+
 	await fs.rm(ssrOutDir, { recursive: true })
 
 	return

packages/orga-build/lib/endpoint.js

@@ -0,0 +1,49 @@
+/**
+ * @typedef {Object} EndpointContext
+ * @property {URL} url
+ * @property {Record<string, string>} params
+ * @property {'dev' | 'build'} mode
+ * @property {{ route: string }} route
+ */
+
+/**
+ * @param {Record<string, any>} endpointModule
+ * @param {EndpointContext} ctx
+ * @param {string} method
+ * @returns {Promise<Response>}
+ */
+export async function resolveEndpointResponse(
+	endpointModule,
+	ctx,
+	method = 'GET'
+) {
+	const route = ctx.route.route
+
+	if (method === 'HEAD' && typeof endpointModule.HEAD === 'function') {
+		const res = await endpointModule.HEAD(ctx)
+		if (!(res instanceof Response))
+			throw new Error(`Endpoint route "${route}" HEAD must return Response`)
+		return res
+	}
+
+	if (typeof endpointModule.GET !== 'function') {
+		throw new Error(
+			`Endpoint route "${route}" must export GET(ctx) returning Response`
+		)
+	}
+
+	const res = await endpointModule.GET(ctx)
+	if (!(res instanceof Response)) {
+		throw new Error(`Endpoint route "${route}" GET must return Response`)
+	}
+
+	if (method === 'HEAD') {
+		return new Response(null, {
+			status: res.status,
+			statusText: res.statusText,
+			headers: new Headers(res.headers)
+		})
+	}
+
+	return res
+}