davaux 0.8.0

package/src/router/scanner.ts

@@ -0,0 +1,272 @@
+import { existsSync } from 'node:fs'
+import { readdir } from 'node:fs/promises'
+import { basename, dirname, join, relative } from 'node:path'
+import type {
+  IslandFile,
+  LayoutFile,
+  MiddlewareFile,
+  RouteFile,
+  RouteType,
+  ScanResult,
+} from '../types.js'
+
+// Maps file suffix → HTTP route type. Longer suffixes first (more specific).
+const SUFFIX_MAP: [suffix: string, type: RouteType][] = [
+  ['.page.tsx', 'page'],
+  ['.page.ts', 'page'],
+  ['.page.jsx', 'page'],
+  ['.page.js', 'page'],
+  ['.get.tsx', 'get'],
+  ['.get.ts', 'get'],
+  ['.get.jsx', 'get'],
+  ['.get.js', 'get'],
+  ['.post.tsx', 'post'],
+  ['.post.ts', 'post'],
+  ['.post.jsx', 'post'],
+  ['.post.js', 'post'],
+  ['.put.tsx', 'put'],
+  ['.put.ts', 'put'],
+  ['.put.jsx', 'put'],
+  ['.put.js', 'put'],
+  ['.patch.tsx', 'patch'],
+  ['.patch.ts', 'patch'],
+  ['.patch.jsx', 'patch'],
+  ['.patch.js', 'patch'],
+  ['.delete.tsx', 'delete'],
+  ['.delete.ts', 'delete'],
+  ['.delete.jsx', 'delete'],
+  ['.delete.js', 'delete'],
+  ['.head.ts', 'head'],
+  ['.head.js', 'head'],
+  ['.options.ts', 'options'],
+  ['.options.js', 'options'],
+]
+
+// Files beginning with _ are framework-reserved (layouts, middleware, etc.)
+const LAYOUT_NAMES = new Set(['_layout.tsx', '_layout.ts', '_layout.jsx', '_layout.js'])
+
+const ERROR_PAGE_NAMES = new Set(['_error.tsx', '_error.ts', '_error.jsx', '_error.js'])
+
+const MIDDLEWARE_NAMES = new Set([
+  '_middleware.tsx',
+  '_middleware.ts',
+  '_middleware.jsx',
+  '_middleware.js',
+])
+
+function resolveRouteSuffix(
+  filename: string,
+  suffixMap: [string, RouteType][],
+): [stripped: string, type: RouteType] | null {
+  for (const [suffix, type] of suffixMap) {
+    if (filename.endsWith(suffix)) return [filename.slice(0, -suffix.length), type]
+  }
+  return null
+}
+
+function segmentToParam(segment: string): {
+  pattern: string
+  param: string | null
+} {
+  const catchAll = segment.match(/^\[\.\.\.([^\]]+)\]$/)
+  if (catchAll) return { pattern: `*${catchAll[1]}`, param: catchAll[1] }
+  const m = segment.match(/^\[([^\]]+)\]$/)
+  if (m) return { pattern: `:${m[1]}`, param: m[1] }
+  return { pattern: segment, param: null }
+}
+
+function fileToUrlPattern(rel: string): {
+  urlPattern: string
+  params: string[]
+} {
+  const params: string[] = []
+  const segments = rel.split('/').map((seg) => {
+    const { pattern, param } = segmentToParam(seg)
+    if (param) params.push(param)
+    return pattern
+  })
+
+  if (segments.at(-1) === 'index') segments.pop()
+
+  const raw = `/${segments.join('/')}`
+  return { urlPattern: raw.replace(/\/+$/, '') || '/', params }
+}
+
+async function walk(dir: string, files: string[] = []): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true })
+  for (const entry of entries) {
+    const full = join(dir, entry.name)
+    entry.isDirectory() ? await walk(full, files) : files.push(full)
+  }
+  return files
+}
+
+/**
+ * Recursively scan `islandsDir` for client island component files.
+ * Files beginning with `_` are ignored. Returns an empty array when the
+ * directory does not exist.
+ */
+export async function scanIslands(islandsDir: string): Promise<IslandFile[]> {
+  if (!existsSync(islandsDir)) return []
+
+  const islands: IslandFile[] = []
+
+  async function walkIslands(dir: string): Promise<void> {
+    const entries = await readdir(dir, { withFileTypes: true })
+    for (const entry of entries) {
+      const full = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        await walkIslands(full)
+      } else if (/\.(tsx?|jsx?)$/.test(entry.name) && !entry.name.startsWith('_')) {
+        const id = entry.name.replace(/\.(tsx?|jsx?)$/, '')
+        islands.push({ filePath: full, id })
+      }
+    }
+  }
+
+  await walkIslands(islandsDir)
+  return islands
+}
+
+// Which HTTP methods does each route type respond to?
+// Mirrors the METHOD_TYPES map in handler.ts, inverted per type.
+const TYPE_METHODS: Record<RouteType, string[]> = {
+  page: ['GET', 'HEAD', 'POST'], // POST only when an `action` export is present, but we warn conservatively
+  get: ['GET', 'HEAD'], // HEAD checks 'get' in its allowed list
+  post: ['POST'],
+  put: ['PUT'],
+  patch: ['PATCH'],
+  delete: ['DELETE'],
+  head: ['HEAD'],
+  options: ['OPTIONS'],
+}
+
+function checkConflicts(routes: RouteFile[], routesDir: string): void {
+  // Group routes by URL pattern — conflicts only possible within the same pattern.
+  const byPattern = new Map<string, RouteFile[]>()
+  for (const route of routes) {
+    const group = byPattern.get(route.urlPattern) ?? []
+    group.push(route)
+    byPattern.set(route.urlPattern, group)
+  }
+
+  for (const [pattern, group] of byPattern) {
+    if (group.length < 2) continue
+
+    for (let i = 0; i < group.length; i++) {
+      for (let j = i + 1; j < group.length; j++) {
+        const a = group[i]
+        const b = group[j]
+        const overlap = TYPE_METHODS[a.type].filter((m) => TYPE_METHODS[b.type].includes(m))
+        if (overlap.length === 0) continue
+
+        const aRel = relative(routesDir, a.filePath)
+        const bRel = relative(routesDir, b.filePath)
+
+        if (a.type === b.type) {
+          console.warn(
+            `[davaux] warning: duplicate ${a.type} route at ${pattern}\n` +
+              `  ${aRel}\n` +
+              `  ${bRel}\n` +
+              `  Only the first will be used.`,
+          )
+        } else {
+          // Explicit method routes sort before page routes, so they always win.
+          const winner = a.type !== 'page' ? aRel : bRel
+          console.warn(
+            `[davaux] warning: ${overlap.join(' + ')} ${pattern} matched by both ${aRel} (${a.type}) and ${bRel} (${b.type}) — ${winner} takes priority`,
+          )
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Recursively scan `routesDir` for route, layout, middleware, and error-page files.
+ * Routes are sorted so static segments beat dynamic segments, and explicit
+ * HTTP-method routes beat page routes at the same URL pattern.
+ *
+ * @param extraSuffixes - Additional `[suffix, RouteType]` pairs contributed by
+ *   plugins (e.g. `[['.page.md', 'page']]` from `@davaux/markdown`).
+ */
+export async function scanRoutes(
+  routesDir: string,
+  extraSuffixes: [string, RouteType][] = [],
+): Promise<ScanResult> {
+  const suffixMap: [string, RouteType][] = [...SUFFIX_MAP, ...extraSuffixes]
+  const allFiles = await walk(routesDir)
+  const routes: RouteFile[] = []
+  const layouts: LayoutFile[] = []
+  const middlewares: MiddlewareFile[] = []
+  let errorPage: string | undefined
+
+  for (const filePath of allFiles) {
+    const rel = relative(routesDir, filePath)
+    const name = basename(rel)
+
+    // Framework-reserved file: layout
+    if (LAYOUT_NAMES.has(name)) {
+      layouts.push({ filePath, dirPath: dirname(filePath) })
+      continue
+    }
+
+    // Framework-reserved file: error page (first one wins)
+    if (ERROR_PAGE_NAMES.has(name)) {
+      errorPage ??= filePath
+      continue
+    }
+
+    // Framework-reserved file: scoped middleware
+    if (MIDDLEWARE_NAMES.has(name)) {
+      middlewares.push({ filePath, dirPath: dirname(filePath) })
+      continue
+    }
+
+    // Skip other underscore-prefixed files silently
+    if (name.startsWith('_')) continue
+
+    const resolved = resolveRouteSuffix(rel, suffixMap)
+    if (!resolved) {
+      // Warn about .tsx files sitting directly in the routes root — they look like
+      // components that belong in src/components/ rather than src/routes/.
+      if (name.endsWith('.tsx') && dirname(filePath) === routesDir) {
+        console.warn(
+          `[davaux] warning: ${rel} is not a route file and will be ignored.\n` +
+            `  If this is a shared component, move it to src/components/ or co-locate it\n` +
+            `  in a subdirectory alongside the routes that use it.`,
+        )
+      }
+      continue
+    }
+
+    const [stripped, type] = resolved
+    const { urlPattern, params } = fileToUrlPattern(stripped)
+    routes.push({ filePath, urlPattern, type, params })
+  }
+
+  checkConflicts(routes, routesDir)
+
+  // Explicit method routes (post, get, put, …) beat page routes at the same URL.
+  // This matters for POST: both `login.post.ts` and `login.page.tsx` (with defineAction)
+  // resolve to `/login`, but the explicit file should always win.
+  const TYPE_PRIORITY: Record<string, number> = { page: 1 } // all explicit methods default to 0
+
+  // Static segments before dynamic before catch-all; shorter paths before longer; explicit methods before pages.
+  const dynamicWeight = (pattern: string) => {
+    const segs = pattern.split('/')
+    if (segs.some((s) => s.startsWith('*'))) return 1000
+    return segs.filter((s) => s.startsWith(':')).length
+  }
+
+  routes.sort((a, b) => {
+    const ad = dynamicWeight(a.urlPattern)
+    const bd = dynamicWeight(b.urlPattern)
+    if (ad !== bd) return ad - bd
+    if (a.urlPattern.length !== b.urlPattern.length)
+      return a.urlPattern.length - b.urlPattern.length
+    return (TYPE_PRIORITY[a.type] ?? 0) - (TYPE_PRIORITY[b.type] ?? 0)
+  })
+
+  return { routes, layouts, middlewares, errorPage }
+}

package/src/server/index.ts

@@ -0,0 +1,49 @@
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http'
+import type { CompiledApp } from '../router/handler.js'
+import { dispatch } from '../router/handler.js'
+
+/** Options for `startServer()`. */
+export interface ServerOptions {
+  /** TCP port to listen on. Default: `3000` */
+  port?: number
+  /** Hostname or IP address to bind to. Default: `'localhost'` */
+  hostname?: string
+  /**
+   * Called before the Davaux dispatcher on every request.
+   * Return `true` to signal that the request was fully handled (the dispatcher is skipped).
+   */
+  onRequest?: (req: IncomingMessage, res: ServerResponse) => boolean | Promise<boolean>
+}
+
+/**
+ * Start the HTTP server and begin accepting requests.
+ *
+ * @param app - A compiled app from `buildApp()`, or a factory function that returns one
+ *   (useful in development when the app is rebuilt between requests).
+ * @returns The underlying `http.Server` instance.
+ */
+export function startServer(app: CompiledApp | (() => CompiledApp), options: ServerOptions = {}) {
+  const { port = 3000, hostname = 'localhost', onRequest } = options
+  const getApp = typeof app === 'function' ? app : () => app
+
+  const server = createServer(async (req, res) => {
+    if (onRequest) {
+      const handled = await onRequest(req, res)
+      if (handled) return
+    }
+
+    dispatch(req, res, getApp()).catch((err) => {
+      console.error('[davaux] Unhandled dispatch error:', err)
+      if (!res.headersSent) {
+        res.writeHead(500, { 'Content-Type': 'text/plain' })
+        res.end('Internal Server Error')
+      }
+    })
+  })
+
+  server.listen(port, hostname, () => {
+    console.log(`\n  davaux  http://${hostname}:${port}\n`)
+  })
+
+  return server
+}

package/src/signal.ts

@@ -0,0 +1,39 @@
+// Server-side stubs — synchronous values, no reactive graph.
+// The reactive implementations in davaux/client are used inside islands.
+
+/** A reactive signal: a `[getter, setter]` tuple. On the server this is backed by a plain variable. */
+export type Signal<T> = [get: () => T, set: (value: T) => void]
+
+/** A read-only derived value: a zero-argument getter that returns the current result. */
+export type ReadonlySignal<T> = () => T
+
+/** Server-side stub — returns a getter/setter pair backed by a plain variable. */
+export function createSignal<T>(value: T): Signal<T> {
+  return [
+    () => value,
+    (v: T) => {
+      value = v
+    },
+  ]
+}
+
+/** Server-side stub — runs `fn` once synchronously, no reactive tracking. */
+export function createEffect(fn: () => void): void {
+  fn()
+}
+
+/** Server-side stub — evaluates `fn` immediately and returns a static getter. */
+export function createMemo<T>(fn: () => T): ReadonlySignal<T> {
+  const result = fn()
+  return () => result
+}
+
+/** Server-side stub — calls `fn` directly with no tracking context. */
+export function untrack<T>(fn: () => T): T {
+  return fn()
+}
+
+/** Server-side stub — calls `fn` directly with no batching. */
+export function batch<T>(fn: () => T): T {
+  return fn()
+}

package/src/ssg.ts

@@ -0,0 +1,253 @@
+import { existsSync } from 'node:fs'
+import { cp, mkdir, writeFile } from 'node:fs/promises'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { dirname, join, relative } from 'node:path'
+import { frameworkWarn } from './errors.js'
+import { buildApp, dispatch } from './router/handler.js'
+import type { GetStaticPathsFn, ScanResult } from './types.js'
+
+/** Options for `generateStatic()`. All directory paths should be absolute. */
+export interface SsgOptions {
+  /** Output directory for generated HTML files. */
+  outDir: string
+  /** Build output directory — used to locate `_davaux` assets to copy across. */
+  distDir: string
+  /** Public directory to copy into `outDir` after generation. */
+  publicDir: string
+  /** Scanned route manifest from `scanRoutes()`. */
+  scan: ScanResult
+  /** Client JS bundle URLs injected into every generated page. */
+  clientScripts: string[]
+  /** Client CSS URLs injected into every generated page. */
+  clientStylesheets: string[]
+  /** Compiled path to `src/middleware.ts` — applied to every SSG render request. */
+  appMiddlewarePath?: string
+  /**
+   * Controls the URL-to-filename mapping.
+   * - `'always'` — `/about` → `about/index.html` (default)
+   * - `'never'`  — `/about` → `about.html`
+   */
+  trailingSlash?: 'always' | 'never'
+  /** Base path for subdirectory deployments (e.g. `'/docs'`). */
+  basePath?: string
+  /** Generate a `404.html` from `_error.tsx`. Default: `true` when `_error.tsx` is present. */
+  notFound?: boolean
+  /**
+   * Generate a `sitemap.xml`. Pass `false` to disable, or `{ baseUrl }` to enable.
+   * `baseUrl` is prepended to every URL (e.g. `'https://example.com'`).
+   */
+  sitemap?: false | { baseUrl: string }
+}
+
+function makeMockReq(pathname: string): IncomingMessage {
+  return {
+    method: 'GET',
+    url: pathname,
+    headers: { host: 'localhost', cookie: '' },
+    on(event: string, listener: (...args: unknown[]) => void) {
+      // Immediately signal end of body so ctx.json()/ctx.form() resolve empty
+      if (event === 'end') setImmediate(() => listener())
+      return this
+    },
+    removeListener() {
+      return this
+    },
+  } as unknown as IncomingMessage
+}
+
+function makeMockRes(): [ServerResponse, () => { status: number; html: string }] {
+  let status = 200
+  let body = ''
+  let sent = false
+  let ended = false
+  const hdrs: Record<string, string | string[]> = {}
+
+  const res = {
+    get statusCode() {
+      return status
+    },
+    set statusCode(v: number) {
+      status = v
+    },
+    get headersSent() {
+      return sent
+    },
+    get writableEnded() {
+      return ended
+    },
+    writeHead(code: number) {
+      status = code
+      sent = true
+    },
+    end(data?: string | Buffer) {
+      if (data != null) body = typeof data === 'string' ? data : data.toString('utf-8')
+      ended = true
+    },
+    getHeader: (name: string) => hdrs[name.toLowerCase()],
+    setHeader(name: string, value: string | string[]) {
+      hdrs[name.toLowerCase()] = value
+    },
+  } as unknown as ServerResponse
+
+  return [res, () => ({ status, html: body })]
+}
+
+function urlToFile(
+  outDir: string,
+  url: string,
+  trailingSlash: 'always' | 'never' = 'always',
+): string {
+  const trimmed = url.replace(/^\//, '').replace(/\/$/, '')
+  if (!trimmed) return join(outDir, 'index.html')
+  if (trailingSlash === 'never') return join(outDir, `${trimmed}.html`)
+  return join(outDir, trimmed, 'index.html')
+}
+
+function toSitemapUrl(
+  baseUrl: string,
+  basePath: string,
+  urlPath: string,
+  trailingSlash: 'always' | 'never',
+): string {
+  const base = baseUrl.replace(/\/$/, '')
+  const bp = basePath.replace(/\/$/, '')
+  const trimmed = urlPath.replace(/\/$/, '')
+  const path = !trimmed ? '/' : trailingSlash === 'never' ? trimmed : `${trimmed}/`
+  return `${base}${bp}${path}`
+}
+
+/**
+ * Pre-render all static pages in the route manifest and write them to `outDir`.
+ * Pages with `export const prerender = false` are skipped. Dynamic routes must
+ * export `getStaticPaths` to supply the parameter sets to render.
+ *
+ * Also generates `404.html` (from `_error.tsx`) and `sitemap.xml` when
+ * configured, and copies `_davaux` assets and `public/` into `outDir`.
+ */
+export async function generateStatic(opts: SsgOptions): Promise<void> {
+  const {
+    outDir,
+    distDir,
+    publicDir,
+    scan,
+    appMiddlewarePath,
+    trailingSlash = 'always',
+    basePath = '',
+    notFound,
+    sitemap,
+  } = opts
+
+  // Prepend basePath to injected asset URLs so the rendered HTML references the correct paths
+  const clientScripts = opts.clientScripts.map((s) => `${basePath}${s}`)
+  const clientStylesheets = opts.clientStylesheets.map((s) => `${basePath}${s}`)
+
+  const app = buildApp(scan, false, clientScripts, clientStylesheets, appMiddlewarePath, basePath)
+
+  // Collect all URL paths to render
+  const toRender: string[] = []
+
+  for (const route of scan.routes) {
+    if (route.type !== 'page') continue
+
+    const mod = (await import(route.filePath)) as Record<string, unknown>
+    if (mod.prerender === false) continue
+
+    if (route.params.length === 0) {
+      toRender.push(route.urlPattern)
+    } else {
+      const fn = mod.getStaticPaths as GetStaticPathsFn | undefined
+      if (typeof fn !== 'function') {
+        frameworkWarn(
+          `[ssg] skipping ${route.urlPattern} — dynamic route has no getStaticPaths export`,
+          `Add a getStaticPaths export to ${relative(process.cwd(), route.filePath)}:\n\n` +
+            `  export const getStaticPaths = async () => [\n` +
+            `    { params: { /* param: value */ } },\n` +
+            `  ]`,
+        )
+        continue
+      }
+      const paths = await fn()
+      for (const sp of paths) {
+        let url = route.urlPattern
+        for (const [k, v] of Object.entries(sp.params)) url = url.replace(`:${k}`, String(v))
+        toRender.push(url)
+      }
+    }
+  }
+
+  await mkdir(outDir, { recursive: true })
+
+  let count = 0
+  const renderedUrls: string[] = []
+
+  for (const url of toRender) {
+    try {
+      const req = makeMockReq(url)
+      const [res, result] = makeMockRes()
+      await dispatch(req, res, app)
+      const { status, html } = result()
+
+      if (status >= 300) {
+        frameworkWarn(`[ssg] ${url} → HTTP ${status} — skipping`)
+        continue
+      }
+
+      const file = urlToFile(outDir, url, trailingSlash)
+      await mkdir(dirname(file), { recursive: true })
+      const full = html.trimStart().startsWith('<!') ? html : `<!DOCTYPE html>${html}`
+      await writeFile(file, full, 'utf-8')
+      renderedUrls.push(url)
+      count++
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err)
+      frameworkWarn(`[ssg] ${url} failed to render — skipping\n  ${detail}`)
+    }
+  }
+
+  // Generate 404.html for static hosts (Netlify, GitHub Pages, etc.)
+  const shouldGenerateNotFound = notFound !== false && scan.errorPage != null
+  if (shouldGenerateNotFound) {
+    try {
+      const req = makeMockReq('/__davaux_404__')
+      const [res, result] = makeMockRes()
+      await dispatch(req, res, app)
+      const { html } = result()
+      const full = html.trimStart().startsWith('<!') ? html : `<!DOCTYPE html>${html}`
+      await writeFile(join(outDir, '404.html'), full, 'utf-8')
+      console.log('[davaux] Generated 404.html')
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err)
+      frameworkWarn(`[ssg] Failed to render 404.html — skipping\n  ${detail}`)
+    }
+  }
+
+  // Generate sitemap.xml
+  if (sitemap !== false && sitemap != null) {
+    const entries = renderedUrls
+      .map(
+        (url) =>
+          `  <url><loc>${toSitemapUrl(sitemap.baseUrl, basePath, url, trailingSlash)}</loc></url>`,
+      )
+      .join('\n')
+    const xml =
+      `<?xml version="1.0" encoding="UTF-8"?>\n` +
+      `<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n` +
+      `${entries}\n` +
+      `</urlset>\n`
+    await writeFile(join(outDir, 'sitemap.xml'), xml, 'utf-8')
+    console.log(`[davaux] Generated sitemap.xml (${renderedUrls.length} URL(s))`)
+  }
+
+  // Copy _davaux assets (islands, client bundle, CSS)
+  const assetsDir = join(distDir, '_davaux')
+  if (existsSync(assetsDir)) {
+    await cp(assetsDir, join(outDir, '_davaux'), { recursive: true })
+  }
+
+  // Copy public/ directory if present
+  if (existsSync(publicDir)) {
+    await cp(publicDir, outDir, { recursive: true })
+  }
+
+  console.log(`[davaux] Generated ${count} static page(s) → ${relative(process.cwd(), outDir)}/`)
+}

package/src/test/actions.test.ts

@@ -0,0 +1,40 @@
+import assert from 'node:assert/strict'
+import { describe, test } from 'node:test'
+import { makeApp, request, route } from './helpers.js'
+
+describe('form actions', () => {
+  test('GET renders the page normally', async () => {
+    const app = makeApp({ routes: [route('action.page.ts', '/')] })
+    const { status, body } = await request(app, { url: '/' })
+    assert.equal(status, 200)
+    assert.ok(body.includes('form'))
+    assert.ok(!body.includes('submitted:'))
+  })
+
+  test('POST with action rerenders page with actionResult', async () => {
+    const app = makeApp({ routes: [route('action.page.ts', '/')] })
+    const { status, body } = await request(app, {
+      method: 'POST',
+      url: '/',
+      body: 'name=Alice',
+    })
+    assert.equal(status, 200)
+    assert.ok(body.includes('submitted:Alice'))
+  })
+
+  test('POST to page without action returns 405', async () => {
+    const app = makeApp({ routes: [route('index.page.ts', '/')] })
+    const { status } = await request(app, { method: 'POST', url: '/' })
+    assert.equal(status, 405)
+  })
+
+  test('action can parse multiple form fields', async () => {
+    const app = makeApp({ routes: [route('action.page.ts', '/')] })
+    const { body } = await request(app, {
+      method: 'POST',
+      url: '/',
+      body: 'name=Bob&extra=ignored',
+    })
+    assert.ok(body.includes('submitted:Bob'))
+  })
+})