@opentf/web-cli 1.0.0 → 1.2.0

package/README.md

@@ -0,0 +1,49 @@
+# @opentf/web-cli
+
+The **OTF Web** dev toolchain — the `otfw` command. A [Rolldown](https://rolldown.rs)-driven
+CSR dev server, a production build, and static pre-rendering (SSG), with the IR
+compiler ([`@opentf/web-compiler`](https://github.com/Open-Tech-Foundation/Web-App-Framework/tree/main/packages/web-compiler))
+running as a transform plugin. Runs on [Bun](https://bun.sh).
+
+## Installation
+
+```bash
+bun add -d @opentf/web-cli
+```
+
+It depends on `@opentf/web-compiler` (the prebuilt compiler binary) and expects
+`@opentf/web` in your project. The fastest way to a working setup is
+[`@opentf/create-web`](https://github.com/Open-Tech-Foundation/Web-App-Framework/tree/main/packages/create-web).
+
+## Commands
+
+The project root is the current working directory — its `index.html` plus a
+file-based `app/` route tree (`page.jsx`, `layout.jsx`, `404.jsx`).
+
+```bash
+otfw dev            # start the dev server (watch + live reload)
+otfw build          # production bundle in dist/ (hashed, code-split, minified)
+otfw build --ssg    # build, then pre-render each static route to HTML
+otfw serve          # build, then server-render each route per request (SSR)
+```
+
+- **`dev`** — bundles the route graph through Rolldown with the compiler as a
+  transform, serves it, and live-reloads on change. Picks port 3000, scanning
+  upward if it's taken; an explicit `--port` fails fast if busy.
+- **`build`** — emits `dist/` from your `index.html`, compiling and hashing local
+  stylesheets (TailwindCSS v4 supported out of the box).
+- **`build --ssg`** — additionally pre-renders each route with `getStaticPaths`
+  into static HTML.
+- **`serve`** — builds `dist/`, then runs a per-request SSR server: assets are served
+  from `dist/` and every navigation is server-rendered through the same path SSG uses.
+  Picks port 3000 (scanning upward), or `--port` for an explicit one. Phase 1: the page
+  becomes interactive via the client bundle (CSR mount); hydration is a later phase.
+
+`OTFWC_BIN` overrides the compiler binary location. Published installs under
+`node_modules` use the packaged compiler, even when the app lives inside a Cargo
+workspace; this repository's own source checkout may build and use
+`target/debug/otfwc` for compiler development.
+
+## License
+
+MIT © [Open Tech Foundation](https://github.com/Open-Tech-Foundation)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opentf/web-cli",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "OTF Web dev toolchain — the Rolldown-driven CSR dev server, production build, and SSG.",
   "type": "module",
   "bin": {
@@ -9,6 +9,10 @@
   "exports": {
     ".": "./src/cli.js"
   },
+  "scripts": {
+    "test": "bun test tests/",
+    "test:e2e": "bun tests/e2e/serve.mjs && bun tests/e2e/hydrate-browser.mjs"
+  },
   "files": [
     "src"
   ],
@@ -16,7 +20,7 @@
     "bun": ">=1.0.0"
   },
   "dependencies": {
-    "@opentf/web-compiler": "0.1.0",
+    "@opentf/web-compiler": "0.2.0",
     "@tailwindcss/node": "4.2.2",
     "@tailwindcss/oxide": "4.2.2",
     "rolldown": "1.0.0-rc.17",

package/src/build.js

@@ -21,13 +21,53 @@ import {
   cssPlugin,
   discoverPages,
   entrySource,
+  injectBeforeBody,
+  loadConfig,
+  loadDocsPlugins,
   loadProject,
   otfwPlugin,
+  readHtmlShell,
+  runBlogFeed,
+  runDocsSearchIndex,
+  runLlmsFiles,
+  runLastUpdated,
+  stampHydrateSentinel,
 } from "./shared.js";
+import { fmtMs, step } from "./reporter.js";
 
 const hash = (s) => Bun.hash(s).toString(16).padStart(16, "0").slice(0, 8);
 
-export async function runBuild() {
+// Site origin for absolute canonical / sitemap/feed URLs. Priority: `--base-url=`
+// flag, then `otfw.config` (`{ site: { url } }`).
+export function resolveBaseUrl(config, argv = process.argv) {
+  const flag = argv.find((a) => a.startsWith("--base-url="));
+  if (flag) return flag.slice("--base-url=".length).replace(/\/+$/, "");
+  if (config?.site?.url) return String(config.site.url).replace(/\/+$/, "");
+  return "";
+}
+
+export function buildRequiresBaseUrl(config, argv = process.argv) {
+  return argv.includes("--ssg") || !!config?.docs || !!config?.blog;
+}
+
+function requireBaseUrl(config, argv = process.argv) {
+  const baseUrl = resolveBaseUrl(config, argv);
+  if (baseUrl || !buildRequiresBaseUrl(config, argv)) return baseUrl;
+  console.error(
+    `✗ site.url is required for this production build.\n` +
+      `  Add it to otfw.config.js:\n\n` +
+      `  export default defineDocsConfig({\n` +
+      `    site: { url: "https://example.com" }\n` +
+      `  })\n\n` +
+      `  Or pass --base-url=https://example.com`,
+  );
+  process.exit(1);
+}
+
+export async function runBuild(options = {}) {
+  const projectRoot = process.cwd();
+  const config = await loadConfig(projectRoot);
+  const baseUrl = requireBaseUrl(config);
   const { root, appDir, webEntry, otfwc, exclude } = loadProject();
   const t0 = performance.now();
 
@@ -37,6 +77,15 @@ export async function runBuild() {
     process.exit(1);
   }
 
+  // Build the client for hydration when there will be server markup to adopt — the
+  // SSR server (`runBuild({ hydrate: true })`) and `--ssg` pre-rendered pages. A
+  // plain CSR build mounts into an empty `#app`, so it keeps the leaner CSR bundle.
+  const hydrate = options.hydrate ?? process.argv.includes("--ssg");
+
+  // Docs generator: resolve `@opentf/web-docs/nav` to the build-time nav tree when
+  // the project has a `docs` config block.
+  const docsPlugins = await loadDocsPlugins(root, appDir, config, exclude);
+
   const outDir = join(root, "dist");
   rmSync(outDir, { recursive: true, force: true });
   mkdirSync(join(outDir, "assets"), { recursive: true });
@@ -45,12 +94,27 @@ export async function runBuild() {
   const tmp = join(root, ".otfw");
   mkdirSync(tmp, { recursive: true });
   const entry = join(tmp, "entry.js");
-  writeFileSync(entry, entrySource(pages, appDir));
+  writeFileSync(entry, entrySource(pages, appDir, undefined, config?.i18n, config?.nav));
+
+  console.log("\n  OTF Web — production build\n");
 
+  // Phase 1: compile every route/component (jsx/mdx → native DOM) and bundle. The
+  // compiler runs as a synchronous subprocess per file, so the per-file `onResult`
+  // is what drives the live progress line.
+  const buildStep = step("Compiling routes & components");
+  let compiled = 0;
   const result = await build({
     input: entry,
     resolve: { alias: { "@opentf/web": webEntry }, extensions: EXTENSIONS },
-    plugins: [otfwPlugin(otfwc, { failOnError: true }), cssPlugin()],
+    plugins: [
+      ...docsPlugins,
+      otfwPlugin(otfwc, {
+        failOnError: true,
+        target: hydrate ? "hydrate" : "csr",
+        onResult: (id) => buildStep.update(`${basename(id)}  (${++compiled})`),
+      }),
+      cssPlugin(),
+    ],
     output: {
       dir: join(outDir, "assets"),
       format: "esm",
@@ -58,6 +122,9 @@ export async function runBuild() {
       chunkFileNames: "[name]-[hash].js",
       minify: true,
     },
+    // The compiler runs a subprocess per file, so it dominates plugin time by design;
+    // silence Rolldown's plugin-timing advisory rather than print it every build.
+    checks: { pluginTimings: false },
   });
   rmSync(tmp, { recursive: true, force: true });
 
@@ -65,20 +132,15 @@ export async function runBuild() {
   const bundleHref = `/assets/${entryChunk.fileName}`;
 
   // Compose dist/index.html from the project shell: strip module entry scripts,
-  // compile + hash any local stylesheet links, and inject the bundle.
-  const indexPath = join(root, "index.html");
-  let html = existsSync(indexPath)
-    ? readFileSync(indexPath, "utf8")
-    : `<!doctype html><html lang="en"><head>
-<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
-<title>OTF Web</title></head><body><div id="app"></div></body></html>`;
-
-  html = html.replace(
-    /<script\s+type=["']module["'][^>]*src=[^>]*>\s*<\/script>\s*/gi,
-    "",
-  );
+  // compile + hash any local stylesheet links, and inject the bundle. When the
+  // client was built for hydration, stamp the `#app` sentinel so the client adopts
+  // the server markup (this shell is also the SSG pre-render template, so each
+  // pre-rendered page inherits the sentinel).
+  let html = readHtmlShell(root);
+  if (hydrate) html = stampHydrateSentinel(html);
 
   // Compile each local <link rel="stylesheet" href="/..."> and rewrite the href.
+  buildStep.update("styles");
   const links = [...html.matchAll(/<link\b[^>]*\bhref=["']([^"']+)["'][^>]*>/gi)];
   for (const [, href] of links) {
     if (!href.startsWith("/")) continue; // leave external/CDN links alone
@@ -93,34 +155,70 @@ export async function runBuild() {
   }
 
   const script = `<script type="module" src="${bundleHref}"></script>\n`;
-  html = html.includes("</body>")
-    ? html.replace("</body>", `${script}</body>`)
-    : html + script;
+  html = injectBeforeBody(html, script);
   writeFileSync(join(outDir, "index.html"), html);
 
+  const chunks = result.output.filter((o) => o.type === "chunk").length;
+  buildStep.done(`Compiled ${pages.length} routes · bundled ${chunks} chunks`);
+
   // SSG: pre-render each route into static HTML using the shell we just composed
   // (so per-route files carry the same bundle + stylesheet links).
   let ssg = null;
   if (process.argv.includes("--ssg")) {
     const { runPrerender } = await import("./prerender.js");
-    ssg = await runPrerender({ root, pages, webEntry, otfwc, shellHtml: html, outDir });
+    // Per-page last-updated map (git/frontmatter) for the article:modified_time tag.
+    const lastUpdated = await runLastUpdated(root, appDir, config, exclude);
+    const ssgStep = step("Pre-rendering pages");
+    let ssgCompiled = 0;
+    ssg = await runPrerender({
+      root,
+      pages,
+      webEntry,
+      otfwc,
+      shellHtml: html,
+      outDir,
+      baseUrl,
+      docsPlugins,
+      lastUpdated,
+      i18n: config?.i18n,
+      onCompile: (id) => ssgStep.update(`compiling ${basename(id)}  (${++ssgCompiled})`),
+      onRender: (done, total) => ssgStep.update(`rendering ${done}/${total}`),
+    });
+    ssgStep.done(
+      `Pre-rendered ${ssg.count} page(s)` +
+        (ssg.skipped.length ? ` · ${ssg.skipped.length} dynamic route(s) skipped` : ""),
+    );
   }
 
   // Copy the public/ directory (static assets served at the root), if present.
   const publicDir = join(root, "public");
   if (existsSync(publicDir)) cpSync(publicDir, outDir, { recursive: true });
 
-  const chunks = result.output.filter((o) => o.type === "chunk").length;
-  const ms = Math.round(performance.now() - t0);
-  console.log(`\n  OTF Web build`);
-  console.log(`  → dist/  (${pages.length} routes, ${chunks} chunks) in ${ms}ms`);
-  if (ssg) {
-    console.log(
-      `  → pre-rendered ${ssg.count} HTML file(s)` +
-        (ssg.skipped.length
-          ? `; skipped ${ssg.skipped.length} dynamic route(s) without getStaticPaths`
-          : ""),
+  // Docs search: index the pre-rendered HTML with Pagefind (when SSG + opted in).
+  let search = null;
+  if (ssg && config?.docs?.search?.provider === "pagefind") {
+    const searchStep = step("Building search index");
+    search = await runDocsSearchIndex(root, config, outDir, (done, total) =>
+      searchStep.update(`${done}/${total} pages`),
     );
+    searchStep.done(`Search index — ${search?.pages ?? 0} page(s)`);
   }
-  console.log("");
+
+  // Blog RSS + Atom feeds (when a `blog` block is configured). Written
+  // after the public/ copy so project-supplied feed overrides aren't clobbered.
+  if (config?.blog) {
+    const feedStep = step("Generating blog feeds");
+    const feed = await runBlogFeed(root, appDir, config, outDir, baseUrl, exclude);
+    if (feed) feedStep.done(`Blog feeds — ${feed.count} post(s) → ${feed.paths.join(", ")}`);
+    else feedStep.done("Blog feeds — skipped");
+  }
+
+  if (config?.docs || config?.blog) {
+    const llmsStep = step("Generating LLM context");
+    const llms = await runLlmsFiles(root, appDir, pages, config, outDir, baseUrl);
+    if (llms) llmsStep.done(`LLM context — ${llms.paths.join(", ")}`);
+    else llmsStep.done("LLM context — skipped");
+  }
+
+  console.log(`\n  → dist/  ready in ${fmtMs(performance.now() - t0)}\n`);
 }

package/src/cli.js

@@ -3,6 +3,7 @@
 //
 //   otfw dev     start the CSR dev server (watch + live-reload)
 //   otfw build   produce a static production bundle in dist/
+//   otfw serve   build, then run the per-request SSR server
 //
 // The project root is the current working directory (its index.html + app/),
 // like `vite` / `next`.
@@ -20,6 +21,11 @@ switch (cmd) {
     await runBuild();
     break;
   }
+  case "serve": {
+    const { runServe } = await import("./serve.js");
+    await runServe();
+    break;
+  }
   default: {
     if (cmd && cmd !== "help" && cmd !== "--help" && cmd !== "-h") {
       console.error(`unknown command: ${cmd}\n`);
@@ -28,6 +34,7 @@ switch (cmd) {
     console.log("usage:");
     console.log("  otfw dev     start the dev server");
     console.log("  otfw build   build for production (dist/); --ssg to pre-render routes");
+    console.log("  otfw serve   build, then run the per-request SSR server (--port to override)");
     process.exit(cmd && cmd !== "help" && cmd !== "--help" && cmd !== "-h" ? 1 : 0);
   }
 }