feat: Phase 3 — production builder and manifest system

Added production build orchestrator and manifest:

production-builder.ts:
- buildForProduction(): discovers routes, generates assets, compiles
  all templates, writes .output/ directory structure
- Produces fingerprinted runtime/router JS, compiled template JSONs,
  SPA fragments, and a manifest.json for the production server

manifest.ts:
- BuildManifest type with routes, assets, and build metadata
- generateManifest(), writeManifest(), loadManifest()

Output structure:
  .output/
    public/__stx/runtime.[hash].js, router.[hash].js
    server/pages/*.compiled.json
    server/fragments/*.html
    manifest.json

Tested end-to-end: 2 pages compiled in 38ms.
All 8028 tests pass.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: glennmichael123

packages/stx/src/index.ts

@@ -67,9 +67,11 @@ export * from './loops'
 export * from './markdown'
 export * from './middleware'
 export * from './parser'
+export * from './manifest'
 export * from './placeholder'
 export * from './process'
 export * from './production-build'
+export * from './production-builder'
 export * from './release'
 export * from './router'
 export * from './scaffolding'

packages/stx/src/manifest.ts

@@ -0,0 +1,107 @@
+/**
+ * Build Manifest
+ *
+ * Tracks all routes, assets, and dependencies for a production build.
+ * Used by the production server to serve pre-built pages.
+ *
+ * @module manifest
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+/**
+ * A route entry in the build manifest.
+ */
+export interface ManifestRoute {
+  /** URL pattern (e.g. '/jobs', '/player/:id') */
+  pattern: string
+  /** Path to the compiled template JSON */
+  compiledPath: string
+  /** Path to the SPA fragment HTML */
+  fragmentPath: string
+  /** Whether this route has dynamic content (server scripts) */
+  isDynamic: boolean
+  /** Whether this is a dynamic route with params (e.g. [id].stx) */
+  hasParams: boolean
+}
+
+/**
+ * Asset entries in the build manifest.
+ */
+export interface ManifestAssets {
+  /** Signals runtime filename */
+  runtime: string
+  /** Router script filename */
+  router: string
+  /** CSS bundle filename */
+  css?: string
+}
+
+/**
+ * The complete build manifest.
+ */
+export interface BuildManifest {
+  /** Manifest version for compatibility checks */
+  version: 1
+  /** Build timestamp */
+  buildTime: string
+  /** All routes */
+  routes: ManifestRoute[]
+  /** Fingerprinted asset filenames */
+  assets: ManifestAssets
+  /** Output directory (relative to project root) */
+  outputDir: string
+}
+
+/**
+ * Generate a build manifest from compiled pages and assets.
+ */
+export function generateManifest(
+  routes: ManifestRoute[],
+  assets: ManifestAssets,
+  outputDir: string,
+): BuildManifest {
+  return {
+    version: 1,
+    buildTime: new Date().toISOString(),
+    routes,
+    assets,
+    outputDir,
+  }
+}
+
+/**
+ * Write the manifest to disk.
+ */
+export function writeManifest(manifest: BuildManifest, outputDir: string): void {
+  const manifestPath = path.join(outputDir, 'manifest.json')
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2))
+}
+
+/**
+ * Load and validate a build manifest from disk.
+ * Returns null if the manifest doesn't exist or is invalid.
+ */
+export function loadManifest(outputDir: string): BuildManifest | null {
+  const manifestPath = path.join(outputDir, 'manifest.json')
+  if (!fs.existsSync(manifestPath)) {
+    return null
+  }
+
+  try {
+    const content = fs.readFileSync(manifestPath, 'utf-8')
+    const manifest = JSON.parse(content) as BuildManifest
+
+    if (manifest.version !== 1) {
+      console.warn(`[stx] Manifest version mismatch: expected 1, got ${manifest.version}`)
+      return null
+    }
+
+    return manifest
+  }
+  catch (error) {
+    console.warn('[stx] Failed to load manifest:', error)
+    return null
+  }
+}

packages/stx/src/production-builder.ts

@@ -0,0 +1,182 @@
+/**
+ * Production Builder
+ *
+ * Orchestrates the production build process:
+ * 1. Discover routes from pages/
+ * 2. Generate shared assets (runtime, router)
+ * 3. Compile all templates
+ * 4. Generate CSS from all pages
+ * 5. Write .output/ directory
+ * 6. Generate manifest
+ *
+ * @module production-builder
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { createRouter, type Route } from './router'
+import { buildRuntimeAsset, buildRouterAsset, type BuiltAsset } from './build-assets'
+import { compileTemplate, type CompiledTemplate } from './template-compiler'
+import { generateManifest, writeManifest, type ManifestRoute, type ManifestAssets } from './manifest'
+
+/**
+ * Production build configuration.
+ */
+export interface ProductionBuildOptions {
+  /** Project root directory (default: process.cwd()) */
+  root?: string
+  /** Output directory (default: '.output') */
+  outputDir?: string
+  /** Enable debug/dev runtime (default: false) */
+  debug?: boolean
+  /** Components directory */
+  componentsDir?: string
+  /** Partials directory */
+  partialsDir?: string
+  /** Layouts directory */
+  layoutsDir?: string
+}
+
+/**
+ * Result of a production build.
+ */
+export interface ProductionBuildResult {
+  /** Number of pages compiled */
+  pageCount: number
+  /** Generated asset filenames */
+  assets: ManifestAssets
+  /** Output directory path */
+  outputDir: string
+  /** Build duration in ms */
+  duration: number
+}
+
+/**
+ * Build the stx application for production.
+ *
+ * Produces a `.output/` directory with:
+ * - `public/__stx/` — fingerprinted runtime and router JS
+ * - `public/assets/` — bundled CSS
+ * - `server/pages/` — compiled template JSON files
+ * - `server/fragments/` — SPA navigation fragments
+ * - `manifest.json` — route map and asset hashes
+ */
+export async function buildForProduction(options: ProductionBuildOptions = {}): Promise<ProductionBuildResult> {
+  const startTime = Date.now()
+  const root = path.resolve(options.root || process.cwd())
+  const outputDir = path.resolve(root, options.outputDir || '.output')
+
+  console.log('[stx build] Starting production build...')
+
+  // ── 1. Clean output directory ──
+  if (fs.existsSync(outputDir)) {
+    fs.rmSync(outputDir, { recursive: true })
+  }
+
+  // Create directory structure
+  const dirs = [
+    path.join(outputDir, 'public', '__stx'),
+    path.join(outputDir, 'public', 'assets'),
+    path.join(outputDir, 'server', 'pages'),
+    path.join(outputDir, 'server', 'fragments'),
+  ]
+  for (const dir of dirs) {
+    fs.mkdirSync(dir, { recursive: true })
+  }
+
+  // ── 2. Discover routes ──
+  console.log('[stx build] Discovering routes...')
+  const routes = createRouter(root)
+  console.log(`[stx build] Found ${routes.length} routes`)
+
+  // ── 3. Generate shared assets ──
+  console.log('[stx build] Generating shared assets...')
+  const runtimeAsset = buildRuntimeAsset(options.debug)
+  const routerAsset = buildRouterAsset()
+
+  // Write runtime JS
+  fs.writeFileSync(
+    path.join(outputDir, 'public', '__stx', runtimeAsset.filename),
+    runtimeAsset.content,
+  )
+  // Write router JS
+  fs.writeFileSync(
+    path.join(outputDir, 'public', '__stx', routerAsset.filename),
+    routerAsset.content,
+  )
+
+  console.log(`[stx build] Runtime: ${runtimeAsset.filename} (${(runtimeAsset.content.length / 1024).toFixed(1)}KB)`)
+  console.log(`[stx build] Router: ${routerAsset.filename} (${(routerAsset.content.length / 1024).toFixed(1)}KB)`)
+
+  // ── 4. Compile all templates ──
+  console.log('[stx build] Compiling templates...')
+  const compiledPages: CompiledTemplate[] = []
+  const manifestRoutes: ManifestRoute[] = []
+
+  for (const route of routes) {
+    try {
+      const compiled = await compileTemplate(route.filePath, route.pattern, {
+        componentsDir: options.componentsDir,
+        partialsDir: options.partialsDir,
+        layoutsDir: options.layoutsDir,
+        debug: options.debug,
+      })
+
+      compiledPages.push(compiled)
+
+      // Replace asset hash placeholders with actual fingerprinted filenames
+      compiled.html = compiled.html
+        .replace(/runtime\.__STX_HASH__\.js/g, runtimeAsset.filename)
+        .replace(/router\.__STX_HASH__\.js/g, routerAsset.filename)
+      compiled.fragment = compiled.fragment
+        .replace(/runtime\.__STX_HASH__\.js/g, runtimeAsset.filename)
+        .replace(/router\.__STX_HASH__\.js/g, routerAsset.filename)
+
+      // Write compiled template
+      const safeRouteName = route.pattern === '/' ? 'index' : route.pattern.slice(1).replace(/\//g, '-').replace(/[[\]]/g, '_')
+      const compiledPath = path.join('server', 'pages', `${safeRouteName}.compiled.json`)
+      const fragmentPath = path.join('server', 'fragments', `${safeRouteName}.html`)
+
+      fs.writeFileSync(
+        path.join(outputDir, compiledPath),
+        JSON.stringify(compiled, null, 2),
+      )
+      fs.writeFileSync(
+        path.join(outputDir, fragmentPath),
+        compiled.fragment,
+      )
+
+      manifestRoutes.push({
+        pattern: route.pattern,
+        compiledPath,
+        fragmentPath,
+        isDynamic: compiled.hasServerScripts,
+        hasParams: route.pattern.includes(':') || route.pattern.includes('['),
+      })
+
+      console.log(`[stx build]   ✓ ${route.pattern}`)
+    }
+    catch (error) {
+      console.error(`[stx build]   ✗ ${route.pattern}:`, error instanceof Error ? error.message : error)
+    }
+  }
+
+  // ── 5. Generate manifest ──
+  const assets: ManifestAssets = {
+    runtime: runtimeAsset.filename,
+    router: routerAsset.filename,
+  }
+
+  const manifest = generateManifest(manifestRoutes, assets, outputDir)
+  writeManifest(manifest, outputDir)
+
+  const duration = Date.now() - startTime
+  console.log(`\n[stx build] Done in ${duration}ms — ${compiledPages.length} pages compiled`)
+
+  return {
+    pageCount: compiledPages.length,
+    assets,
+    outputDir,
+    duration,
+  }
+}